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RESPONSIBILITY 


Neither Commodore Data A/S or any of this company's dealers 
or distributors give any guarantee expressed or implied 
concerning the COMAL computer language as described in this 
manual and tutorial. The language and documentation are 
sold "as is" with no claim being made as to its quality or 
Suitability for specific tasks. The risk concerning the 
quality and performance of this product rests with the 
buyer. Should this product prove defective after purchase, 
it is the buyer (and neither the producer UniComal A/S, 
Commodore Data A/S, nor any distributor or dealer) who must 
take full responsibility for service, repair and any other 
costs accrued due to errors or defects. This is true even 
if the producer of the program has been given prior notice 
of the possible existence of such errors or defects. 


COPYRIGHT 


The computer language COMAL for the Commodore 64 1s covered 
by the following copyright: 


© Commodore Data A/S and UniComal ApS 1985 


This manual is covered by copyright ©Commodore Data A/S, 
Denmark, 1985. No part of the system, the program cartridge 
or this manual may be reproduced, stored in a data retrieval 
system or in any way be transmitted electronically or 
mechanically, photocopied or be duplicated in any other way 
without the prior written permission of the owner of the 
copyright. Copying the COMAL cartridge is forbidden; 
however the Demonstration diskette or tape may be copied 
freely. 


ASSISTANCE 


If you have any comments concering this COMAL manual or the 
programming language itself, please pass them along to your 
dealer. Commodore Data A/S has made every effort to assure 
that the contents of this manual are correct and complete 
and than the programming language itself functions as it 
should. Every error discovered by users will be corrected 
aS soon aS possible. Your help in this connection will be 
sincerely appreciated, not least by other COMAL users. 
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INTRODUCTION 


WHAT IS COMAL? 


Welcome to the world of COMAL programming! Many feel that 
COMAL is close to being an ideal programming language for 

microcomputers, incorporating as it does the best features 
of both Basic, Logo and Fascal. You are about to iearn a 

programming language which offers, among other things, the 
following features: 


* COMAL (COMmon Algorithmic Language) extends Basic, giving 
the language many of the powerful instructions of Fascal. 


* COMAL retains the convenient operating environment of 
Basic, and many COMAL statements will be tamiliar to 
Basic users. 


* COMAL for the Commodore 64 incorporates the easy to use 
turtle graphics which has made Logo famous. 


* COMAL on the C-464 offers useful guidance when errors 
occur during program entry. The language contains 
structures for error handling during execution of 
programs. 


* The language encourages structured programmina with 
access to loop statements like: 


REPEAT - UNTIL 
WHILE - DO — ENDWHILE : 


flexible conditionals like 


IF — THEN — ELIF —- ELSE - ENDIF 
CASE - OF —- WHEN - OTHERWISE -— ENDCASE A 


and valuable building 
blocks like procedures and 
functions. 


* COMAL for the Commodore 64 
Qives the user full access 
to the many special 
facilities which have made 
the C464 the most popular 
microcomputer in its class: 


high res color graphics 
sprites 

music 

joystick 

paddles 

lightpen 

and much more... 
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THE ORIGINS OF COMAL 


COMAL originated in response to the needs of computer users 
in Denmark. Berge Christensen taught computer programming 
in the early 1970's to students at a small college in 
Tander, near the German—-Danish border. He found that the 
students often wrote terrible programs. They were hard to 
read, hard to de-bug and hard to maintain. Dr. Christensen 
consulted colleaques at the Institute of Computer Science at 
the Danish University of Arhus. A researcher there by the 
name of Benedict Lsefsted recommended that Christensen read 
the book, Systematic Programming by Niklaus Wirth. 


Many readers will recognize Niklaus Wirth (of the Swiss 
Federal Institute of Technology in Zurich) as the father of 
the Pascal programming language. Inspired by Wirth’s clear 
formulation of the principles of structured programming, 
Christensen contacted Benedict Lsefsted. They agreed that 
the Basic language offered the user a very convenient 
operating environment. Basic was highly interactive. It 
allowed direct execution of instructions from the keyboard 
and required neither prior definition of variables nor the 
compilation process before a program could be run. 


These features were ideal for a teaching environment. On 
the other hand Basic lacked the ability to use long, 
descriptive variable names and did not provide the elegant 
syntax of Pascal. If Basic could be augmented with these 
features, it would encourage the writing of clearer, better- 
structured programs. These men went to work with their 
colleagues to formulate requirements for the COMAL 
programming ianguage. The language was developed and 
perfected during the 1970's. COMAL grew to maturity 
together with the personal microcomputer. 


The current version of COMAL 80, which you now own, is 
version 2.0. It is the product of standardization efforts 
by an international. committee composed of representatives 
for users and industry. The COMAL kernel was agreed upon by 
this group. It is composed of all COMAL instructions which 
must be common to all versions of the COMAL lanquage. 
Special features, such as the use of graphics, music, 
sprites and other special features of the Commodore 64, can 
be added as special packages. More about that later'! 


COMAL AND COMMODORE 


During the growth in popularity of the COMAL language, the 
Danish distributors of Commodore computers have played a 
leading role. With the advent of the inexpensive and 
popular microcomputer, in particular the Commodore 64, a 
group of young software enthusiasts, Jens Erik Jensen, 
Mogens Kier, Helge Lassen and Lars Laursen formed a company, 
UniComal ApS. In cooperation with the Danish distributor 
and later with Commodore Data A/S, they developed COMAL 

for the C-64. 


When you have worked through the tutorial and written some 
of your own programs, we hope you will agree that the 
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efforts of these pioneers have not been in vain! 


USING THIS TUTORIAL 


If you examine the Table of Contents, you will see that this 
manual begins with a chapter on setting up your computer and 
Plugging in your COMAL cartridge. Next comes an easy to 
read, step-by-step introduction to COMAL programming. By 
the time you get to Chapter 2? we will assume that you have 
Overcome the initial uncertainty (which everyone feels) when 
beginning with a new computer language. 

Chapter 3 presents a systematic description of the most 
commonly used COMAL instructions. Here you will be 
presented with features for serious programming and begin to 
write your own COMAL programs. 


Every programmer needs a good resource with information on 
the precise meaning of the most important facilities which 
are available in the language he uses. We have tried to 
provide this essential information - with examples - ina 
systematic form in Chapter 4, COMAL Overview. For those 
readers who require even more complete information on the 
definition of COMAL syntax, a comprehensive document is 
availiable: 


Len Lindsay, COMAL HANDBOOK, i983. 
Reston Fublishing, 11480 Sunset Hills Road 
Reston, VA 22090 USA (702) 437-8900 


(also available from Frentice Hall in Engiand or trom 
COMAL USERS GROUP, 3501 Groveland Terrace, Madison WI 
52716 USA) 


Note that the COMAL USERS GROUF also puts out a newsletter. 
It contains many program examples and other useful 
information and is highly recommended. It is always a big 
advantage for the beginner to be in touch with more 
experienced users. 


The package concept is one of those teatures which make 
COMAL for the Commodore 64 particularly powerful. When a 
special feature of your Commodore 64 (for example high 
resolution graphics) is to be used in a program, a package 
can be activated. When that feature is not needed, you 
don't activate the package. (Your programs will run 
slightly faster, because you only add the extra orders you 
need.) Turtle graphics is available, if you want to use it. 
Peripherals like joysticks, light pens, and paddles can be 
accessed with special packages of orders which extend the 
standard COMAL language. A complete description on the use 
of these packages is presented in Chapter 5. 


Chapter 6 includes additional information on the handling of 
files in COMAL. This information will be particularly 
useful to those users who may wish to take advantage of 
COMAL to write programs for record keeping and data handling 
which require advanced facilities of the Commodore disk 
drive. 
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In Chapter 7 the use of peripheral equipment is covered. 
This includes the control ports to which you can attach 
joystick, paddles, or light pen, and the RS232 interface, 
IEEE interface, parallel port and other cartridges. This 
last item may be of particular interest to those users who 
may want to develop their own turn-key systems based on the 
Commodore 64. 


Those of you with 16 fingers may want to get inside COMAL, 
learn about the use of Commodore memory and write your own 
machine language programs. This is also possible using 
COMAL. Read Chapter 8 to learn more about how this can be 
done. 


This Tutorial concludes with a collection of information 
assembled ina series of Appendices. Here you will find the 
Commodore ASCII character codes, color codes for graphics, 
some tips on calculating with COMAL, use of the keyboard and 
the COMAL screen editor, use of strings, error messages and 
some useful programs and procedures. Finally there is an 
Index to help you find information quickly when you need 

it. 


Throughout this tutorial you will encounter a number of 
special symbols designed to emphasize important points or 
warn you Of special hazards: 


~ > “Watch out! A mistake here could get 
you into trouble.” Data can sometimes 
tf, - be lost, or you might ruin a program, if 
ea you are not careful. If you’re 
(2 connecting equipment, you will be warned 


to turn off all power. 


This symbol means, "Here 1S a good 
idea which can save you time and 
effort!" 





“Here is a useful procedure or 
operation which should be followed to 
make your programming easier. 


“Here comes an experiment which will 
be fun to try out!" 
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“This material could be a bit 
difficult to master. FProcede 
carefully!" 





“Here 15 a summary which reviews 
material previously covered in the 


tutorial." 





Work through the tutorial at your own pace. be careful not 
to jump too far ahead before you're ready. Later on you 
should find this tutorial useful as a reterence guide. 


Happy programming! 


Frank Bason & Leo Hej3sholt—Foulsen 
Silkeborg, Denmark 
January 1985 
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CHAPTER 1 - 


SETTING UF YOUR COMPUTER 





YOUR COMPUTER AND ACCESSORIES 


In order to use COMAL, vou will require the following 
equipments: 


* a Commodore 64 computer (or an SxX-64 transportable) 
* the COMAL proagrammina language cartridge 
* a video monitor or a television (color or 5/W) 


It is possible to run COMAL programs without an external 
storage medium - i.e. a disk drive or a tape unit. However , 
as you will soon be writing programs which you will want to 
save, it will be essential to have one of the following: 


* a Datassette tape unit, or 
* a Commodore 1541 disk drive. 


Optional items of equipment for your Commodore 64 - nice to 
have but not essential - include: 


* a Commodore 1526 printer or equivalent. 
* an extra Commodore 1541 disk drive 


When you begin to write longer programs, a printer 15 very 
useful to have. For serious programming you will need 
listings of your programs and printouts of your data. An 
extra disk drive is not an essential item. However, if you 
use your computer a great deal, a second drive will make 
copying programs and files a lot easier. 


Figure 1.1 shows the jack connections on the rear and on the 
right side of your Commodore 64. Refer to this diagram to 
help connect the equipment you will be using. 
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GAME POWER POWER CARTRIOGE CHANNEL wv AUDIONIDEO SERIAL CASSETTE USER 
PORTS SWITCH SOCKET SLOT SELECTOR CONNECTOR CONNECTOR PORT INTERFACE PORT 





Figure 1.1: Accessories and peripheral devices are attached @ 
to your Commodore via the connectors on the rear 
and on the side of the computer. 


Your COMAL cartridge may also be used with the Commodore 
SX-64 portable version of the Commodore 64 computer. The 
SX-64 is illustrated in Figure 1.2. This unit includes both 
a color monitor and a disk drive unit. With a COMAL 
cartridge and the SX-64 you can skip ahead to the section on 
Installation of the COMAL Cartridge. 





Figure 1.2: The Commodore SX-64 transportable computer is 
completely compatible with the Commodore 64. 
The SX-64 features a built-in color monitor and 
disk drive. 


If you have access to a 1541 disk drive, attach it to the 
Commodore 64 via the 6-pole jack on the back panel (the same 
jack can be used for a printer). 
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If you have a printer as well as a disk drive, it can be 
connected to the second jack at the rear of the drive. You 
can use either one of the two connectors on the disk drive 
for the computer and for the extension cable to the printer. 


If you are using a Datassette tape unit, attach it to the 
computer via the 12 pole edge connector (next to the User 
Port). Note that an ordinary tape recorder cannot be used. 


You will find detailed information on the use of these 
accessories in your Commodore 64 manual, and in the disk 
drive, Datassette and printer manuals. 


A typical set-up will look like the illustration in Figure 
1.5. The system shown includes a single disk drive, a 
printer and a portable TV used as a display. 





Figure 1.2: An ideal setup for learning and using the COMAL 
programming language includes a Commodore 64 
computer equipped with a printer, 1541 disk 
drive and a color TV or monitor. 


Don’t turn anything on yet. We will have to install the 
COMAL cartridge before continuing! 


INSTALLING YOUR COMAL CARTRIDGE 


Your COMAL language cartridge is shown in Figure 1.4. It 
must be installed in the cartridge slot at the rear of your 
computer, if you use the Commodore 64. If you have an SX- 
64, then the cartridge slot is on top of the machine on the 
right hand side. 
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Figure 1.4: Your COMAL cartridge allows you to expand the 
power of your Commodore 64 without using 
additional memory. It fits into the cartridge 
slot at the rear of the Commodore 64 (or the top 
of an SX-64). 


Take a closer look at your COMAL cartridge. Note that there 
1S a row of contacts on the edge of the printed circuit 
board which protrudes from the cartridge. There is a square 
label on the front of the cartridge. This must face upward 
when you insert the COMAL cartridge horizontally into the 
cartridge slot of the Commodore 64. (The label will be 
towards the front, when you insert the cartridge into the 
cartridge slot of an SX-64.) 


WARNING: Never insert a cartridge into your 
se, Commodore 64 or SX-64 (and never remove it) with 
$ the power turned on. The power to all peripherals 


t/ 
Gr must be OFF when inserting or removing a 


cartridge! 





When you are sure that the cartridge edge connector is 
properly aligned with the slot in the computer, push the 
cartridge firmly into place using a gentle rocking motion. 
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CONNECTING THE TV OR MONITOR 


POWER SUPPLY 





Figure 1.5: The C-64 can be connected to the UHF input of a 
standard TV receiver. 


Your Commodore 64 is supplied with the following display 
outputs: 


* color monitor signals (audio, composite video and 
luminance) 


* a modulated standard (CUHF channel 36) color TV signal 
The output jacks for these signals are shown in Figure i.l. 


Because the SX-64 has its own color monitor, the following 
discussion will only apply to the Commodore 64. If you will 
be using the SX-64, you can proceed directly to the next 
section on running the demonstration program. 


A color monitor is the most desirable choice of display for 
your Commodore 64, because it will give you the sharpest 
image. If you have a Commodore monitor, just attach one end 
of the connector cable supplied with the monitor to the &8- 
pole connector on the rear panel of the Commodore 64. Plua 
the connectors at the other end of the cable into the three 
phono jacks on the rear panel of the monitor. If you will 
be using a different type of monitor, your dealer will be 
able to assist you to find the proper cable. 


A TV connector cable is supplied with your Commodore 64 for 
those users who will be using a color (or B/W) television 
set for their display. If you will be using a television 
set, insert the phono plug end of the cable into the phono 
jack on the rear panel of your Commodore 64, and plug the 
other end into the antenna input jack on your television 
receiver. 


You must also connect the Commodore transformer to your 
computer. The cable from the power supply is inserted on 
the right hand side of your computer (towards the rear, 
right next to the power switch). 


When all connections have been properly made and all 
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shipping protection has been removed from your disk drive 
and printer, you are ready to turn on your equipment. Turn 
peripherals on first, then turn on the Commodore 64. To do 
this both the switch on the power supply as well as the 
switch on the right side of the computer must be turned on. 


Tune the UHF channel selector of your color TV to find the 
Signal. Adjust the TV receiver for the sharpest possible 
picture. (There is also a fine-tuning screw next to the 
antenna jack on the rear panel of the Commodore 64. If you 
can adjust the TV for a good picture, then adjustment of 
this screw will not be necessary.) 


If all has gone well, the following message should be 
present on your display screen: © 


$$$ Commodore-64 COMAL 80 rev 2.01 $$$ 
(C) 1984 by UniComal & Commodore 
30714 bytes free. 


and the blinking cursor will appear 3 lines below the 
message. If the sound is turned up on your TV or monitor, 
you will also hear a signal, indicating that COMAL is ready 
to go. 


Should any problem arise at this point, turn off your 
equipment at once. Check the setup procedure once again. 
Be sure that the COMAL cartridge is inserted correctly and 
is firmly seated in its socket. Check all cables and be 
sure that there is power at the electrical socket. Check 
your Commodore 64 Instruction Manual. If problems persist, 
contact your Commodore dealer for help. 


THE COMMODORE KEYBOARD 


If you are not familiar with the Commodore keyboard, then 

type anvthing at all, just to get used to it. Try out the 
<SHIFT> and <SHIFT LOCK> keys. If you should make a 

typing error, be sure that the <SHIFT LOCK> key is 

disengaged. then press the "insert or delete key" marked 
<INST/DEL> at the upper right hand side of the keyboard to & 
delete the character just to the left of the cursor. 


You can also move the cursor around the screen using the 
cursor control keys (next to the right hand <SHIFT> key). 
If the <SHIFT> key is depressed and you press <INST/DEL> 
then extra spaces appear, allowing you to make insertions. 
Try out the <CLR/HOME> key with and without the <SHIFT> 
key engaged to learn what it does. 


If you have a black/white TV receiver or monitor, hold down 
the <CTRL> key at the left of the keyboard. Fress the 
letter W at the same time. Doing this will change the 
screen and cursor colors, making the screen easier for you 
to read. If you are using a color TV or monitor, try 
<CTRL> V for a dark blue background and white text. 

More on color changes later on! 





You might try pressing the Commodore Key <C=> (on the 
left hand side of the keyboard) and the <SHIFT> key at 
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the same time. When you do this you will “toggle" the 
display back and forth between capitals and small letters 
and capitals and graphics. Be sure you have selected 
Capitals and small letters. . 


Check: Press the keys <A> <S> <De 
The computer prints a s d 


Press the same keys 
again while holding 
down <SHIFT>. 


The computer prints A S D 


For the time being, the features described here will be 
adequate for proceeding with this tutorial. You will learn 
about additional facilities, as we go along. A complete 
description of the keyboard and the many features of the 
COMAL screen editor .is available in Appendix D. 


RUNNING THE DEMONSTRATION PROGRAM 


If your Datassette tape storage unit or vour disk drive is 
connected properly, you are ready to run programs. Please 
read the instructions which apply to you: 


Using the Datassette: 
{___\ If you are using a Datassette unit for program storage, 


insert the COMAL Demonstration Tape and type: 


load "cs: demoprogram" 
then press the key marked <RETURN>. 


Note that if you intend to use the Datassette from now 
on, you can make it the default unit by typing in the 
command: 


unit "ces" <RETURN> 


Note that a word like RETURN printed within 
brackets < > means to press the key with 
that name instead of spelling out the entire 
word on the keyboard. 


The C-64 responds by printing press play on tape on 
the screen. Be sure that the tape has been spooled 
back to the beginning then start the tape by pressing 
the PLAY button on the Datassette. The computer 
responds: 


ok 
searching for demoprogram 


The screen will go blank for a moment. When the program has 
been located, the following message will be displayed: 
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found demoprogram 


After a minute or so the cursor will begin blinking 
again, indicating that the loading operation is 
completed. (You can interrupt the read-in by pressing 
the Commdore key <C#>.)} You are now ready to run the 
demonstration program. 


If you have difficulty loading the demonstration 
program, you can try the following: 


* Turn off the power to the computer and the 
Datassette, and check again that the tape recorder 
is connected correctly. Is the cable intact and 
plugged all the way in? 


* Be sure you are using the correct tape and that it 
has been spooled all the way back to the beginning 
(all the tape should be on the left hand reel). 


* When you have checked the above points, apply power 
to start COMAL up again. Then repeat the read-in 
procedure. 


* If you still have difficulty, contact you dealer for 
assistance. 


Using a Disk Drives: 


If you have a disk drive, insert the COMAL 
Demonstration Diskette. The label should face upward 
and be on the edge facing you when the diskette is 
inserted (see Figure 1.6). 
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Figure 1.46: Handle the diskette carefully. Open the 
drive door, and insert the diskette into 
the drive as shown. Slowly push the 
diskette all the way into the slot. When 
the diskette is in place, close the drive 
door until you hear it click into place. 


Now type: 
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load "demoprogram*“ 


and press <RETURN>. This order will transfer a copy 
of the program from the diskette to your computer ‘s 
memory. The activity indicator on the drive should 
light up, and the drive will operate for a few seconds. 


Whichever means you have used to load the demonstration 
program, you can now type run and press <RETURN>. Then 
Sit back, relax and enjoy the show! Be sure vour TV or 
monitor sound volume is turned up slightly so music and 
sound effects can be heard. 





You can interrupt the program if you wish bv pressing the 
<RUN/STOP> key. 


=, Be sure to remove the demo diskette and store it 
——n Yr in a safe place before proceding wi e nex 

¢ ] bef di ith th t 
AS section of this chapter. 
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@ If you follow the tutorial in the coming chapters, you 

will soon be able to adapt the powerful features of 
your Commodore 64 with the COMAL programming language - 
high resolution color graphics, sprites, sound and more 
- for use in your own programs. 


PREPARING A STORAGE DISKETTE 


Before we proceed to the introductory tutorial in 
Chapter 2, let's get a blank diskette ready for storing 
your programs. This process is called formatting the 
diskette. Datassette users won’t need to format tapes 
- that is not necessary. But tape users may want to 
read this section anyway to learn more about diskettes 
and how they are used. 


You should interrupt the COMAL demo program so that you 
can enter commands from the keyboard. Press 
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<RUN/STOP>, if you haven't already done so. 


*% Be sure that the demo-diskette has been removed and 
stored away. 


* Take a diskette which is unused (or which can be 
erased). Be sure that the write protection notch 
is uncovered (see Figure 1.6). Covering this notch 
with a piece of tape prevents formatting or changing 
the contents of the disk by saving new files. 


* Insert the diskette correctly into the disk drive, 
and close the drive door, so it clicks into place. 


* Now type the following order: @ 
pass “"nO:imy diskette, Xx" 


When you press <RETURN>D the disk drive will begin to 
operate and continue for about 2 minutes. The disk 
activity light will go out, when the formatting process 
is finished. You can now use this diskette for storing 
your programs and files. 
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A few remarks about the command which you just 
issued from the keyboard: pass indicates to 
COMAL that the subsequent text should be passed to 
the disk drive. The letter nis the code for 
formatting a new diskette, and O means that it 
should be done on the first of your drives (in 
case you have more than one). You are free to 
choose the <diskette name> -— up to 16 char- 
acters. This name (my diskette in this example) 
will appear as a heading whenever you catalogue 
your disk (more about this in Chapter 2). The 
last entry XX may be any two characters. It 
serves as a diskette identifier code. 


REVIEW & 


Your equipment should now be set up and 

ready to use. You have mounted the 

COMAL cartridge, powered up, and 

familiarized yourself with the keyboard. 

You have also read in a demonstration 

program and run it to check out your od 
system. 








The program has given you a preview of the impressive 
potential of this programming language. Finally, if you 
will be using a disk drive, you have formatted a diskette 
which can be used for storage of programs as you work 
through the tutorial chapters which follow. 
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CHAPTER 2 — 


LET ’S GET STARTED! 


WHY LEARN TO PROGRAM? 


The computer is a tool for 
handling information. 

Properly programmed, your 
Commodore 64 can do 
calculations, manipulate text, 
sort data, collect data, 
control machines, create 
images, make sound, and much 
more. The heart of the 
computer is the now well-known 
component called the 
microprocessor. If it is 
connected to sufficient memory 


ane 


—— 





and a means of getting data in a 





and reading data out, we have 


a microcomputer. 


The elementary operations which the microprocessor performs 
on individial bytes of data are very simple. Just adding 
two numbers like 2542 and 9320 together may require the 
microcomputer to perform hundreds of simple operations. Yet 
because each operation only takes a millionth of a second, 
the job is done in a thousandth of a second! 


When you program a computer, it is possible (but by no means 
necessary!) to work with the fundamental binary numbers used 
by the processor. Your Commodore 64 computer uses a 

6510 chip. You can use assembler language it you want to 
program it directly. More on this subject is available in 
Chapter &. 


To make life easier for themselves, programmers have evolved 
higher level languages which allow the use of very simple 
orders to accomplish a large number of elementary processor 
Operations. A statement like: 


print 23543 + 9320 
is an example of a high level order. 


This statement can be thought of as a procedure with two 
inputs. The procedure causes the two numbers to be added 
together and printed on an output device, say a display 
screen. 


An ideal computer language allows the programmer to group 
sets of orders together to perform more complex tasks and to 
Give them a new name. For example, it would be nice to have 
an order like 


interest (12533 ,8) 
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which could compute the interest accumulated by an 
investment of 12535 dollars (or pounds) during an eight year 
period. While everyone using a computer language will want 
to add numbers, not everyone will require this particular 
procedure. So the ideal language will include a large 
number of useful standard procedures and make it easy for 
the programmer to construct his Own special ones. 


COMAL is such a language. It 1S a procedure oriented 

language which includes many clear and useful elementary 

orders for custom building your own procedures. Your 

procedures may be so useful that they themselves can be used 
again in other programs or in other procedures which handle 
larger tasks. The COMAL operating enviroment makes this 

easy and convenient to do. When you have learned the COMAL © 
language, you will have a very powerful tool indeed to help 

you solve a wide range of problems. 


Learning a powerful programming language is an adventure. 
Adventures can be fun and exciting. But no adventure worthy 
of the name is without challenges and pitfalls. The ability 
to write your own programs will come only with practice, 
persistence, curiousity and patience. You have begun an 
adventure and must be prepared to go through periods of 
trial and testing before you become a seasoned programmer. 


Frogramming is not just for solving serious professional 
problems. It can be fun, too! Just ask any programmer 
after a late evening getting his own game program to work. 
The thrill of bringing a program to life after carefully 
building it up out of its component parts can be compared to 
other highly creative activities. (Don’t ask the programmer 
about this before he or she has found the last bug and 
gotten the program to run!) Frogramming can be used for so 
many purposes that it 1s impossible to provide a complete 
list. Here are just a few; you can probably think of many 
more. Properly programmed, your computer can: 


play a game with graphics to help children learn 

help teach music by showing notes and playing sounds 
prepare an expense summary and compare it with your budget 
keep sales records for a small business 

record and display weather records 

make measurements in the lab or on a production line 
prepare an income tax return and print it out 

help plan and administer a construction project 

compute the heat losses from a building 

provide motivating teaching aids to help students learn 
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A great deal of programming today has to do with games. 
Since the earliest days of programming, programmers have 
loved to use their machines for "play". (Rumor has it that 
in the late 1960's Star Trek was the most popular program 

at many university computing centers.) When computer time 
cost hundreds of dollars an hour, it was a luxury few could 
enjoy. Today microcomputer time costs only a few cents per 
day, SO game programs have proliferated as never before. If 
you want to play computer games or write some yourself, then 
welcome to COMAL. It is a fast language with excellent 
color graphics, sprites and sound effects. The 
possibilities for game programs are endless. 
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Of the many program types, perhaps simulations are the 

most fascinating. You can become the pilot of a World War I 
fighter plane in hot pursuit of enemy planes. Change the 
program parameters, and you are piloting a 747 jet toa 
landing at Paris, London or New York. Or simulate Charles 
Lindberg’s aircraft, the Spirit of Saint Louis on the first 
non-stop New York to Paris flight. Even the flight of the 
Space Shuttle or the Concorde can be effectively simulated 
using a microcomputer. With color graphics and a joystick, 
such simulations can be strikingly realistic. 


But simulations can be much more than this. They can be 
effective tools for learning - both for students and for 
professionals. With simulation programs you can, among many 
other possibilities, examine: 


the financial decisions of a business 

the operation of a solar heating system, 

the operation of a nuclear reactor, 

the motion of charged atomic particles in electric and 
magnetic fields, 

the orbiting of a satellite, 

or the flight of a rocket. 


x kk 


* * 


Again, for those who undertake the adventure of learning to 
program the possibilities are almost unlimited. Limited in 
fact only by your imagination and your ability to use the 
tools which you now own: your Commodore 64 computer and the 
COMAL programming language. Let’s learn more about how to 
use them! 


DIRECT EXECUTION OF COMAL COMMANDS 


Your computer should have the COMAL cartridge installed and 
should be turned on. When you do this the following message 
should appear on the screen: 


$%¢ Commodore-64 COMAL 80 rev 2.01 $$$ 
(C) 1984 by UniComal & Commodore 
30714 bytes free. 


If this message 1s on your screen, then you are ready to 
proceed... 


For a starter, try pressing <CTRL>-V to change the screen 
colors to a pleasing blue with a white cursor and text. If 
you’re using a B/W display, try <CTRLO-W for a gray 
background and black text. 
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IF YOU MAKE A TYPING ERROR: You can delete the 
character just to the left of the cursor by pressing 
the <INST/DEL> key at the upper right of your 
keyboard. (The <SHIFT LOCK> key must not be 
depressed when you do this!) For a complete 
description of the use of the keyboard and a run-down 
on the many editing facilities available with COMAL, 
see Appendix D. 
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The simplest way to start using COMAL is to type some direct 
orders from the keyboard. Try typing: 


print "hello" & 


When you press <RETURN> the word hello should be printed 
on the next line on your display screen. 


It is important to understand that the computer 
first processes your direct orders when you have 
pressed <RETURND, giving in effect an order to 
process the current command line. 


Note that orders may be entered in either lower case or 
upper case. (You toggle the display screen between upper 
case/graphics and lower case/upper case by pressing the 
<C=> and the <SHIFT> keys at the same time.) 


We will assume in this tutorial, unless otherwise 


stated, that the lower case/upper case mode has 
been selected. 


You can also do caiculations 
using direct orders. Try the 
following order, being careful 
NOT to press the «<SHIFT> key 
when typing the + sign: 


print 217+305 


After pressing <RETURN> you 
will see the computer print 
the number 322 on the next 
line. 


You can also mix text and 
numbers in a PRINT order as in 
the following example: 


print "sum #",217+305 





After you have entered the 
order by pressing <RETURN> 
the computer will prints 


sum =522 
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Notice that if you give no other instructions, the text and 
the number will not be separated by any spaces when they are 
Printed. This can be changed by using a semicolon 3. 

If a semicolon is used as a separator, then a blank space 
will be printed to the right of each text segment or number. 


You can also arrange the placement of your text and numbers 
on the screen using the ZONE order. Type: 


zone 10 


We want to repeat the same order used earlier. For a work- 
saver try this little trick: Depress the <SHIFT> key and 
press the cursor up-down key (just below <RETURN>). Move 
the cursor up the screen until it is blinking on the line: 


print “sum =" ,217+3035 


Release the <SHIFT> key and press <RETURN>. Your order 
will be executed again. But this time there will be 109 
spaces between the start of the text to the first digit of 
the number. The ZONE order is used to specify the width of 
the printing columns when text or numbers are separated by 
commas. The default condition ZONE O is set when vou 

start up your system. 


You may want to do some experimenting with ZONE and FRINT 
orders before moving on in this tutorial. This 18 easy to 
do by using the cursor keys to move up and down on the 
screen. Netice that you needn't be at the end of a line on 
the screen for the order to be executed. Notice aiso that 
if extraneous text is on the same line, it will be 
interpreted together with the order you want to execute, and 
an error message will result. You can either delete the 
extra text (<CTRLO-K will delete everything from the 

cursor position to the end of the line), or you can write 
your order on an empty line to avoid this error. You can 
also completely erase the screen by executing the order PAGE 
or by holding down the <SHIFT> key while pressing the 
<CLEAR/HOME> key. 


COMAL has many other facilities for handling text and 
numbers. We'll be getting into these in much greater depth 
later on. Before we proceed to write programs, let's take a 
guick look at how to use the high-resolution graphics 
screen. 


A QUICK LOOK AT TURTLE GRAPHICS 


Your Commodore 64 is almost ready to do turtle graphics as 
s00N aS you power up. Just press <€3> to enhance COMAL 

with the orders in the turtle graphics package. When you 
press <#3> the words USE turtle will appear on the 

screen. Then the appearance of your screen will change. A 
small arrowhead will appear in the middle of the screen, and 
the words USE turtle will now be at the top of the screen 
with the cursor blinking on the next line. You are now 
looking at the split screen with four lines of text 

visible at the top. Fressing <#1> will bring you back to 
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the text screen. If you depress <#5> you will be 

looking at the graphics screen. The entire screen can be 
used for graphics, but you will not be able to see your 
orders as you type them in. Now press <f3> again to get 
back to the split screen. 


Notice that by means of the USE order you have extended 
the COMAL language with a set of extra orders, called a 
package. As you will learn, many other packages are 
available in your COMAL cartridge. Much more about 
packages in Chapter 5! 


If you should want to remove the COMAL extensions 
invoked by the order USE, you can type: 


discard <RETURN> 


This will remove ALL packages from program memory. 
(You cannot remove packages selectively.) Typing new 
will delete your program and deactivate all packages as 
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Let’s see how the turtle (also called the graphics 

cursor or the pen) represented by the arrowhead can move 
around the screen and draw. We’ll use direct commands now 
but we will write a complete program later on in this 
tutorial. 


Turtle graphics orders are so straigtforward that you can 
learn how they work just by trying them out. Try typing: 


forward(50) <RETURN> 
right (90) <RETURN> 


Type the same orders again. You should have a square 
halfway finished on your screen. Use these turtle graphics 
commands again as needed to complete the square. The turtle 
should end up pointing upwards again. 


Now try the following orders (remembering to press 
<RETURN> after each) and observe what effect they have on 
the turtle and the drawing: 


penup 

back (30) 
pendown 
forward (30) 


Notice that if your experimentation brings you too far in 


any direction, the turtle will show up at the other side of 
the screen. 


Type home to bring the turtle back to the center again, 
then type clearscreen to erase the screen. You can also 
type homescs on one line to accomplish this. 

Now trys 


left (90) 
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forward (50) 
setheading (45) 
forward(7O) 


What does each order do? Do some experimenting yourself to 
understand how to move the turtle and make it draw. You 
might want to try the following sequence: 


for side=i to 4 do forward (50) sleft (90) 


This example illustrates a unique feature of COMAL: 
A sequence of instructions separated by a semicolon can be 
executed directly from the keyboard! | 


To illustrate how COMAL actively assists you as 
you type in instructions (if you haven't already 
noticed this), try making intentional errors while 
typing in the previous command: 


type: far <RETURN> 


Not the computer’ s response. 





type: for # <RETURN> 
Note the response. 

type: for i= <RETURN> 
Note response, etc. 


Another aid provided by Commodore COMAL is that 
the error messages are removed from the screen as 
s00n as you have corrected the error and pressed 
<RETURN> or moved the cursor to another line. 
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Note what each of the following orders does: 


hideturtle 
showturtle 


If you have a color display you can also experiment with 


background (<number >) 
pencolor (<number >) 


where <number> 1s a color code. See Appendix KE for a 


list of the graphics color codes. 


The table which follows shows turtle graphics orders with a 
short form for each and a brief description. When you give 
the order use turtle from the keyboard or in a program, 

all these orders as well as all the commands in the 
graphics package become available for you to use. 
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TURTLE SHORT DESCRIPTION 

ORDER FORM 

back (L) Bk CL) move L units backwards 
forward (L) #d (Ll) move L units forward 
background (C) bg (C) background color set to C 
clearscreen cs clears the graphics screen 
home turtle to screen center 
hideturtle ht conceals the drawing cursor 
showturtle st shows the drawing cursor 
pencolor (C) pc (C) sets the drawing color to C 
pendown pd cursor leaves a trace 

penup pu cursor leaves no trace 

left (D) 1t(D) cursor turns D degrees 
right (D) rt(D) cursor turns D degrees right 


setheading (H) seth (H) cursor points to heading H 
H=0 is up, 70 15 right,etc. 


Make careful note of these orders. We will be using them 
again in the program examples which follow. 


WHAT IS A PROGRAM? 


In order for a machine or a computer to do a job, it has to 
be "told" how to do it. In contrast to a human being who 
can base his actions on skills and experience, the machine 
must be given very precise instructions. Nothing must be 
taken for granted. In practice this means writing down a 
list of orders, each of which can be interpreted by the 
computer, describing in detail the job to be performed. 


This could be a very tedious task indeed, if we were obliged 
to give details on how to, say, "add two numbers together" 
each time it had to be done. This is of course not 
necessary. When the computer has been instructed on how to 
interpret the order PRINT x + y where x and y are any 

pair of numbers, it can add any two numbers at all (within 
certain very wide limits - see Appendix C). The same is 
true of other operations we expect the computer to do. A 
few of the most commonly used operations: 


adding, subtracting, multiplying and dividing numbers 
printing numbers and text 

drawing a line from point to point 

making a choice of two paths to follow 

repeating operations a certain number of times, 
selecting different tasks when certain conditions are met, 


x * kK K * 


are defined in a computer language which is relatively 

easy for human operators to use. COMAL is special, because 
this language is regarded by many as a particularly clear, 
powerful and flexible language. 


Let’s try writing a COMAL program to illustrate some of 
these ideas. 


Suppose we want to draw a square on the display screen of 
the computer. Even with no prior knowledge of programming, 
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we could write down a list of the tasks to be accomplished 
using everyday Englishs 


* Get the computer ready to use the screen for graphics. 


* Describe how far to move and how much to turn to draw a 
side of the square. 


* Repeat the above step four times to complete the square. 


Being a bit more specific, we could express this by writing 
the following instructions. We intend to draw a square 75 

"units" on a side starting at the center of the screen. We 
want the sides of the square to be parallel with the edges 

of the screen: 


* Set the turtle graphics mode. 

* Move the pen forward 75 units, and turn right 90 degrees. 
* Move forward 75 units again, and turn right 90 degrees. 

* Move forward 75, and turn right 90. 

* Move forward 75: turn right 90. 


When all this 1s accomplished, we should have a square on 
the screen with the drawing cursor back in 1ts original 
position. It 1s usually good programming practice to ieave 
the turtle at the end of an instruction sequence in the same 
state as it was when the sequence began. This idea is 
particularly important when you begin to write COMAL 
procedures. It makes things easier when you want to builda 
program up using "modules" or “building blocks" which must 
work together to do a job. 


Let’s see how the actual COMAL program would look. Note 
that it may not be clear at once why certain things are 
done. As you progress with this tutorial you will be 
presented with more thorough explanations to reveal most of 
these mysteries! 


First be sure you are using the text screen (press <f1> 

if you have been using graphics). Be sure that no other 
COMAL program is in memory (type new <RETURN>). You will 
probably want to clear the screen and move the cursor to the 
top left side of the screen. Press the <SHIFT> key and 

the <CLR/HOME> key at the same time to do this. 


If you have trouble getting your computer into 
text mode with the screen cleared, there is one 
sure-fire way of getting things straightened out. 
Depress the <RUN/STOP> key and hold it down 

while pressing the <RESTORE> key. This action 
will initiate things without losing your program. 
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Of course you can always turn off the computer 
power switch, wait a few seconds, and turn it on 
again. You should be back in COMAL with the 
greeting message on the screen, ready to go, but 
this solution will erase your program. 


When you prepare a program, the instructions you prepare are 
not executed right away. They are stored in memory and only 
executed when the program is run. You will find that line 
numbers are not important in COMAL except as an aid when 
entering and editing a program. In fact you will be able to 
completely ignore line numbers when your program is 
completed. 


To make program entry easier, press <#4> to get automatic 
line numbering. (You get this by pressing <SHIFT> and the 
<#3> key.) COMAL responds with AUTO. Press <RETURND, 

and automatic line numbering will be engaged. 





The computer should be ready to accept instruction number 
0010. Note that it is usually wisest to number 
instructions with intervals of 10, so that there will be 
room to make insertions in case you discover later on that 
an instruction has been left out. 
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To get rid of automatic line numbering or to 
change it, just press <RUN STOP> instead of 
entering a new line. If you then type auto or 
press <#4> again, you will be back to automatic 
numbering at the line you left. You can add one 
or two numbers to the AUTO command to change the 
starting line and the line number interval. If 
you type auto,5 <RETURN>D the line number 

interval will be 3S (the line numbers will continue 
rom where you were). If you type auto 100,5, 
then line numbering will start at line 100 with a 
line number interval of 5S. 


Recalling our list of plain English tasks to be performed, @ 
we can start with the COMAL orders which must be used to 
prepare the screen for turtle graphics: 


0010 use turtle 


Press <RETURN>D after each order line (although multiple 
orders on the same line separated by 43 are sometimes 
allowed, usually only one order per line is recommended). 

As you enter program lines, COMAL prints the next program 
line number, ready for your next instruction. Type as 
follows to continue with our sample program. Use the cursor 
keys and the <INST/DEL> key as needed to correct any 

typing errors. Feel free to use the abbreviated orders if 
you prefer. 
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0020 splitscreen 

0030 forward(73)> 

0040 right (90) 

0050 forward (735) 

0060 right(90) 

0070 forward(735) 

0080 right(90) 

0090 forward(753) 

0100 right(90) 

0110 while key$=#chr$(0O) do null 


After your experience with the turtle in the last section 
these orders should be easy to understand except perhaps for 
the order in line number 110. We want to keep the graphics 
screen visible after drawing the square. When a COMAL 
program ends while using graphics, control returns 
automatically to the semi-graphics screen, so that you can 
see your orders as you type. Line 110 makes the graphics 
screen remain completely visible until you press any key. 
When key#$ no longer equals the default value chr$(0O), 

the program will continue beyong line 110. When the program 
proceeds beyond this line, there are no more instructions, 
so the program will stop. 


Try running the program. First press <RUN/STOP> to get 
out of AUTO mode. Then type in run. When you press 
<RETURN>, your program will be carried out step by step. 
This process 15 calied executing a program. 
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You can save a little effort if you want by 
pressing <€7> insteaa of typing 1n run. 
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Press <f#1> to return to the text screen. Change the 

program and run it again to see what happens. Try different 
lengths and different angles to make other figures. When 
you have finished experimenting, we li go on to look at some 
additional COMAL orders. 


REPEATING INSTRUCTIONS 


After working with the sample program to draw the square — 
and perhaps after trying to draw pentagons and octagons - 
you may wish it were possible to repeat a given set of 
instructions which you want to use repeatedly. It 1S indeed 
possible. This programming structure is called a 

loop block and 1s one of the most important concepts 1n 
programming. 


There is an easier way to draw a square. Erase program 
memory (using new <RETURN>) and try the following program: 


0010 // program: SQUARE 
0020 // by: <your name> 
0030 use turtle 

0040 splitscreen 

0050 for sides:#1 to 4 do 
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0060 forward (75) 

0070 right (90) 

0060 endfor 

0090 while key$=#chrs$(0) do null 
0100 end // of program 


Fress <RUN/STOP> to stop auto-numbering then write list 
to do a listing of your program. It should look like this: 


0010 // program: SQUARE 

0020 // by: <your name> 

0030 USE turtle 

0040 splitscreen 

0O0S0 FOR sides:= 1 TO 4 DO 

0060 forward (75) 

0070 right (90) & 
0080 ENDFOR sides 

0090 WHILE KEYS=CHRS$(O) DO NULL 

0100 END // of program 


As you can see, it is possible to add titles, bylines and 
other comments to your programs. Just precede them with a 
//. Such statements are not executed, but they will 

appear in your listings. They can also be added after COMAL 
orders ina program line, as in line 100. Notice how COMAL 
indents lines 60-70 in the listing to make the structure of 
the program clearer. The FOR-ENDFOR construction (50-80) 
causes lines 60-70 to be repeated four times. 


Keywords are capitalized in the second listing. Notice also 
that in the second listing the variable sides is 
automatically included after ENDFOR in line 80. This will 
be done after the program has been RUN or SCANned. To SCAN 
your program just press <€8> or issue the direct order 
scan. (This process will aiso check through vour program 
for errors in structure and define any procedures in the 
program.) 


You have seen how COMAL edits your programs to 
provide a clearer listing. From now on in this 
tutorial, we will show programs in their final, 
edited form. It will, however, probably be 
easiest for you to continue typing the programs in 
lower case. Let COMAL do the extra work of 
providing a nice listing for you! 
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Try running the program square. Fress any key to stop the 
program, then press <f1> to return to the full text 
screen. Now let's try some changes to see what happens. 
Can you alter the program to cause it to draw a hexagon (6 
Sides) or an octagon (8 sides)? When orders are to be 
repeated many times, the FOR-ENDFOR construction becomes 
particularly useful. Can you adapt the program, so the 
turtle draws a figure which is close to being a circle? 
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You may have noticed that in order to compiete a 
polygon and end up facing in the same direction as 
when it started, the turtle must turn a total of 
560 degrees. (Those of you who are familiar with 
the computer language Logo, which also uses turtle 
Graphics, may recognize this principle as the 
Total Turtle Trip Theorem.) So to draw a 
regular polygon with number sides, the turtle 
must turn 360/number degrees at each vertex. 
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It 1s of course possible to adapt this program so that it 
will draw a polygon with any number ot sides we choose. To 
do this we will have to indicate the number of sides desired 
and the length of a side by means of INPUT statements. 

Erase program memory (new <RETURN>), and try entering the 
foliowing program: 


0010 // programs polygon 

0020 // by: <your name> 

0030 PAGE // clear the screen 

0040 INPUT "How many sides? ": number 
00350 INPUT “Length of each? “: length 
0060 USE turtle 

0070 splitscreen 

0OOGO0 FOR sides:=1 TO number DO 

0090 forward (length) 

0100 right (360/number ) 

0110 ENDFOR sides 

0120 WHILE KEYS=CHRS(O) DO NULL 

0130 END // of program 


Note that the program is shown here as it would be listed. 
You can enter the program in lower case and without 
indentation, if you wish. Run it to be sure it works as 
expected. 


COMAL PROCEDURES 


Frocedures are modules or building blocks which you can 
create to make your programming easier. There 1s a line in 
the program polygon which lends itself to being redone as 

a procedure. You can make your program easier to read and 
easier to understand by creating a procedure. This 
technique becomes very important when you begin to write 
longer programs! 


Notice that the use of line numbers in COMAL is 
quite different from their use in other line- 
oriented languages such as BASIC. In this respect 
COMAL 1s much more akin to Pascal. Use the RENUM 
order often to "clean up" your program. Because 
no COMAL order ever reters to a line number, you 
can pay much less attention to them. In general 
it is probably best to group your program 
instructions into three sections: 
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beginning: program name, date, comments, 
dimensioning of variables, 
setup of packages, etc. 


middle: the main program sequence 
consisting mainly of 
procedure calls 


end: collection of your procedures 
called by the main program 


Take a look at your program. Consider statement number 120: 


0120 WHILE KEY#=CHR#(0O) DO NULL ’ @ 


used here as in the program square to keep the graphics 
screen visible until any key 1s pressed. It could be made 
into a procedure to keep it from cluttering up the main 
program: 





0140 

0150 PROC wait’ key 

0160 WHILE KEY$=CHR$(O) DO NULL 
0170 ENDPROC wait ’'key 

0180 


Notice here that we have called the procedure wait ‘key. 
The apostrophe ’ is needed to bind the two words 
describing the procedure together into one continuous string 
of characters with no blanks. If this 1s not done, COMAL 
will only interpret the letters before the first blank as 
the procedure name, and an error message will resuit when 
COMAL tries to execute the procedure. 





Add this procedure to your program, and replace line 120 bys: 
0120 wait‘ key 


Now list the procedure (a little trick: use <#6> <RETURN> 
to do this). Notice the following features of the COMAL 
listing: 


* The LIST order indents instructions in the procedure, 
setting the procedure apart and making the program 
listing easier to read. 





* The procedure must be terminated by ENDPROC. If the 
program has been SCANned or RUN, then COMAL includes the 
name of the procedure in the ENDFROC instruction, if 
you have not already done so. 


* The empty statements in lines 140 and 180 are not 
required. They are included to cause this procedure to 
be separated more clearly from others when the program is 
listed. 


The program polygon could be improved further by creating 
a procedure out of the statements which actually draw the 





Chapter 2 - ~39- GETTING STARTED 


polygon. 
The polygon procedure might be typed in like this: 


1200 pi-oc polygon (number , length) 
1210 for sides:#1 to number 
1220 forward (length) 

1230 right (360/number ) 

1240 endfor 

1250 endproc 

1260 


When you SCAN and then LIST the procedure, it should appear 
as follows: 


& 1200 PROC polygon (number ,length) 
1210 FOR sides:=1 to number 
1220 forward (length) 
1230 right (360/number ) 


1240 ENDFOR sides 
1250 ENDPROC polygon 
1240 


There are a few things you should notice about the listing: 


* The procedure name is foilowed by two variable names 
(number ,length) , 1ndicating that the procedure will 
require values for the number of sides ana the length 
ot each side. A protedure need not have any variable 
list after its name (like the procedure wait key). It 
can nave one, two or more indicated. as shown here. 





Again we must call the procedure betore 1t can be 
executed. The original program must be cnanged, so it looks 
like this when RENUMbered and LISTed: 


0010 // program: polygon 
0020 // by: <your name> 
0030 PAGE 

0040 USE turtle 

OOSO splitscreen 


0060 INPUT “How many sides? “: number 
© 0065 INPUT "Length of each? ": length 
0070 


0080 // MAIN PROGRAM 

0090 polygon (number ,length) 

0100 wait ‘key 

0110 END // of MAIN PROGRAM 
0120 

0130 PROC wait’ key 

0140 WHILE KEY$=CHR$(0) DO NULL 
0150 ENDPROC wait ‘key 

0160 

0170 PROC polygon (number ,length) 
0180 FOR sides:=i to number 
0190 forward (length) 

0200 right (360/number ) 

0210 ENDFOR sides 

0220 ENDPROC polygon 

0230 
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As already mentioned, you can check your program betore 
RUNning or LISTing it by using the SCAN order. (Type scan 
<RETURN> or just press <#@8>). When you do this, COMAL 

will check the program structure and “learn" the procedures 
you have defined. If you subsequently write a defined 
procedure name as a direct order, it will be executed. This 
allows you to check your procedures one by one. This 185 a 
real advantage when "debugging" a program! 

A few more remarks are in order: We have used the general 
structure described earlier with a distinct beginning, 
middle and end of the program. The input data is 

defined in lines 60 and 65, the main program is just a few 
lines long (80-119), and the procedures are placed at the 
end of the program. © 


In line 90 the procedure polygon is called. The two 
numbers in parentheses following the procedure name are the 
two variables which the procedure needs to draw the polygon. 
They need not have the same names as the variable names in 
the procedure, although they happen to in this case. It 15 
important, however, that they are in the same order. 


A remark 1s also in order about the line: 


0190 END // of MAIN PROGRAM 


This line 1s not necessary to stop the program. A COMAL 
program will stop when there are no more lines to execute in 
the main program sequence. It is included here to make the 
structure of the main program sequence clearer. This 1s 


largely a question of programming style. You will have 
strong opinions about such matters as you gain programming 
experience! 


SAVING PROGRAMS AND PROCEDURES 
You may want to save your work now that we have begun to 


write programs which could be used again later. Flease 
follow the instructions which apply to you: 


Using a Datasette Tape Units @ 
fa) To save your program polygon on tape, proceed as 


follows: 





* Flace a cassette tape in your tape unit and be sure 
1t 1s rewound to the beginning. 


= CAUTION: If your tape hae a leader with 
aay no magnetic coating on the first few inches 
5D of the tape, advance the tape for a few 
seconds. Otherwise you run the risk of not 
recording the first part of your program. 
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* Type the following direct order on your keyboard: 


save “csrpolygon" <RETURN> 
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* The message Press record & play on Tape wiil 
appear on your screen. 


* Fress RECORD and PLAY on your Tape Unit. Saving 
a short program like polygon shoula only take 
about 15 seconds. 


* When your program 1s peing saved, tne screen wiil be 
blank. 


* When your program has been saved, the message: 
program saved 
snould appear. 


* It 1s strongly recommendea that you repeat tnis 
process, making a second Dackup copy. It will 
probably be most convenient to do this on the otner 
side of your tape 1¢# you use 10 or iS minute data 
cassettes. If you use longer tapes, it will 
probably be best to do it right after the tirst 
recording, to avoid the time-consuming rewind. 
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Most experienced programmers save their 
program file every iS minutes or so while 
working. It’s & good idea to save your 
program whenever you have completed more than 
you would care to lose in case of a power 
loss or other accident. It 1S wise to save 2 
working copies: the current copy 

and the previous copy. With a tape 

recorder you miagnt ao this Dy reversing si1aces 
of your short data tape every time you save 
your program. That way, 1/4 sometning goes 
wrong (‘a power down during the save coula be 
bad news'), you can read in the previous 
version to get things moving again. 

When your program 1S completea ana dae- 
bugged, then you would want to make at least 
two copies of the final working version: an 


Original working version and 4 backup. 
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* Now label your tape, so you know what you nave: 
This takes a few seconds extra time now, but it 
could save you a hassle later, looking fora 
“missing program". 


Using a Disk Drive: 


You will need to use the storage diskette which you 
prepared earlier. If you didn’t do this, follow the 
directions for doing so in the last section of Chapter 1. 
Then proceed as follows: 


* Insert the storage diskette into the a1sk drive. 
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* Now type the following message on your keyboard: 
save "polygon" 


* The drive activity light will go on, and the drive 
motor will be audible for a few seconds as a copy oft 
your program 1S saved to the diskette. You are free 
to use whatever name you wish (Cup to 16 characters). 
Of course 1t 1S wise to choose names which are 
descriptive and make it easy for you to find your 
programs again. Also, it’s a good idea to include the 
program file name as one of the first lines of your 
program in aremark statement. 


* To be sure that your program file has been saved as @ 
planned, type dir (‘or cat) and press <RETURN>. 
This will show you a directory (or catalogue) of 
what ’s stored on the diskette, how many blocks each 
program takes up (1 block = 256 bytes), and how many 
blocks are unused (XXX blocks free.). 


* An extra backup copy of all important programs 
should always be made on another diskette... just in 
case! And while you are developing a program, make a 
copy of the most recent version every 15 minutes or so 
to avoid ioss of work in case of a power failure or 
other unexpected event! It 16 best to have two recent 
copies stored, just in case. 


* He careful to label your diskettes (do it at once!). 
That way you have a better chance of finding your 
programs again. Once you start writing liots of 
programs, your diskettes will multiply like mice! 


It 1s also possible to save your procedures individually. 
This can be done using a form of the LIST order. it 1s 
described in connection with the discussion of more advanced 
file handling in Chapter 6. 


REVIEW @ 


In this chapter you have been presented with information to 
nelp you: 


issue orders directly from the keyboard 
correct typing errors 

use the cursor control keys 

use turtle graphics 

write simple programs using procedures 
use automatic line numbering 

use a Datassette tape unit or a disk drive for storage 





* ek Ok OR OK 


You should have made a special note of the following concepts: 


* 6510 (6502) microprocessor code 

* high level language orders 

* direct execution vs. programmed (deferred) execution 
* the total turtle trip theorem 
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Printing of text and numbers on the text screen 
calling of procedures 

using procedures with variables 

using a simple loop block 


* kk * 


The following COMAL orders and keywords have been presented in 
this chapter: 


PRINT <text or numbers> 
ZONE <spacing? 

forward (<steps>) 

back (<steps>) 
right (< degrees) 

left (<degrees*>) 

penup 

pendown 

USE <package> 
clearscreen 

home 

splitscreen 

showturtle 

hideturtle 

pencolor (<color>) 
background (<color -) 
setheading (<degrees->) 
WHILE —- DO loops 

KEV? -— (checks the keyboard buffer) 


chr#(Q) 

AUTO —- (for automatic program numbering) 
RUN —- (to execute a program) | 

END —- (to mark the end of a program) 

// - (to insert remarks 10 your program) 


FOR —- DO -—- ENDFOR- loops 
INPUT "<input prompt": <variable list-s 
NULL - an order which does nothing at all! 
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If you have worked through this chapter, vou should be 
prepared for the more advanced description ot COMAL 
programming which tollows in the coming chapter. It can be 
helpful to keep in mind that programming can really be boiled 
down to three fundamental elements: 


* Action blocks are groups of instructions which input 
data, perform calculations, draw a picture, output data or 
carry out some other process in the program. 


* Loop blocks are groups of instructions which are repeated 
a number of times. The FOR — DO - ENDFOR sequence and the 
WHILE —- DO construction are two of several types of loop 
blocks available in COMAL. 


* Branch blocks are instruction sequences which include 
decisions about which orders to carry out next. You will 
learn more about this type of instruction in the next 
chapter. 
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FPROGRAMMING WITH COMmMAL 


This chapter is intended to serve as an introduction to how 
to use COMAL for writing programs. COMAL conceots are 
introduced steno by step without treating each concept in 
depth at this stage. Examples are orovided to illustrate 
each new concent. We will caretullyv comment on selected 
programs to explain how they operate. 


We have attemped to select the examoles so that thev not 
oniy treat selected COMAL topics but aiso illustrate your 
Commodore 64’s many facilities. Some exampies nave been 
chosen to provide a more through treatment ot earlier 
mentioned COMAL statements. This chaoter oroaresses from 
quite easy to more advanced proaramminga techniques. Tne 
concept of the aiagorithm is introduced liate in tne 

chapter, and we have made a special effort to iiiustrate tne 
power ot COMAL’s structured programming aids. 


It is not our intention that vou should be satisfied after 
trving our program examples and exercises. They should be 
considered to be agquideposts to neip you find vour wav as vou 
beain to use COMAL. There 1s a areat deai to be explored. 
Don’t be afraid to strike out on your own to exoeriment with 
your own programs. You can return to the tutorial and 
follow it again after satisfving your curiousitv. Manv 
other books about COMAL are becoming avaiiabile. try out 
programs vou find there or in users aroup pubiications. 

More and more articies on COMAL will appear in popular 
computer magazines as news of this excitina ianagquage 
spreads. The best possibie wav to become proficient at this 
language will be toa use it to write orograms which can heio 
you in your education, professionai work or for 
entertainment. 


ACQUIRE GOOD PROGRAMMING HABITS 


Everyone who writes programs wili sooner or iater develop 
his or her own programming ‘style’. In the beginning. 
however, it can be heipful to follow a few guidelines. You 
mav want to keep the following points in mind when you set 
out to solve a new programming probiem: 


* Type new to delete any earlier program from working 
memory. 


* Then type auto 100 to engage automatic line 
numbering. 





* Go right ahead with the main program. Express the 
problem to be solved as a list of ‘procedures’ to be 
carried out. It may be a good idea to include them in 
a LOOP...ENDLOOP structure, if thev are to be repeated 
again and again. Don’t worry too much about makina 
errors. COMAL’s flexible editing facilities will make 
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it easy to straighten things out later. 


* When the structure of the main program sequence is 
clear, procede to begin writing the individual 
procedures. If a particular task is complex, break it 
down into smaller procedures. This technique is calied 
“top-—down’ design. 


* LIST your program often to be sure that it looks like 
vou expect it to. This will not always be the case! 
Use renum to make room for extra instructions if 
necessary. Don’t worry about line numbers. Use 
renum often to clean things up. 


* AS your proaram nears completion, or you have compieted 
@ large procedure, execute a scan of vour program to 
check for correct structure. 


* After Llistina ano scanning correct possibie errors 
using the COMAL editing orders. Check Anpendix C for 
further information on how this is done. Be careful to 
make backup-copies of your program from time to time; 
this 1S quick and easy to do using COMAL. 


* When your program appears to be error-free, try it out 
by typing the order run. Most often the program can 
be stopped again by simply pressing «<RUN/STOF:;. I+ 
this doesn’t work. try pressing «RUN/STOF> and 
RESTORE? (corresponding to “reset"). 


* When your program is completed and checked, save a copy 
on vour diskette or tape for use later. The order 
save "<programnavn>" can be used if you have a disk 
drive, or use save "cs:<programnavn>" for a 
Datassette tape unit. (Don’t forget to make a backup!) 
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Please note that in the foilowing pages all 
programs are shown as they will appear after a 
scan has been issued. During program entry you 
need not worry about upper/lower case (except of 
course in text names). Nor do you need to include 
extra blanks to emphasize program structure. The 
COMAL system will take care of this for you when 
you scan the program. 


A FIRST CALCULATION 


The first example illustrates how the computer handles 
numbers: 


Program 1s 


new 
auto 100 
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0100 // compute an average 

0110 number as: =7 

0120 numberb: #15 

0130 average: = (number at+numberb) /2 

0140 PRINT "The average of the numbers" 
0150 PRINT numberas "“and"s3;numberb 

0160 PRINT “is"; average 

0170 END 


After enterina the proaqram check it using scan and list. 
Correct any errors. 


Type run then press the <RETURN>-key (or just press <f7>). 
Notes about Program is 


The two // slashes in line 100 indicate. that the line is 
a comment line which the system will not process. 


Computers "remember" numbers and other quantities bv means 
of variables: A variable 1s a name which can represent a 
numerical value. Program 1 contains 3 variables: 

numbera, numberb and average. 


In line 110 the variable numbera is assianed the value 

7, and in line 120 the variable numberb is assianed the 
vaiue 13. Thus variables are given values by means of the 
COMAL assignment operator :=. The svmbol := 1s aiso 


called a dynamic equals sign. 


if you use an ordinary equality sign ® when 

typing in a prooram, the COMAL svstem wili replace 
it by the dynamic equals sign after a SCAN or RUN 
order has been executed. 





A variable name must always begin with a ietter ana mav 
consist of a maximum of 80 characters (i.e. letters, numbers 
or special characters). If a name is terminated with #, ¢# 
or (), it has special meaning, as will be clarified iater. 
The symbols a, a#, at and a() are all considered to 
represent the same name within a Given context. 
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In line 130 the expression (numberatnumberb)/2 (meaning 
add numbera and numberb, and then divide the sum by 2) 

is calculated. Then this value is assigned to the variable 
aver age. 


NB: The order of the variable and the exoression is 
important. The expression on the right hand side of the 
assignment operator is computed first, then the variable 
on the left is assigned this value. 


Reversing the order of the variable name and the expression 
will cause an error message to appear when the program line 
1s entered. 


Lines 140 to 160 display the result using PRINT statements. 
Notice how easy it is to combine numbers and text on the 
screen. 


In line 140 the text between the quotation marks is printed. 


In line 150 the value of numbera is printed first. Then 
comes the text and, and finally the value of numberb. 
Notice the use of the semicolon (3) between the numbers 
and the text. The semicolon is not printed, but it is 
needed as a separation mark between the different parts of 
the line. 


In line 160 the text is followed by the value of average 
is printed. 


Note in connection with this example that: 


* The printout starts on a new line after each PRINT 
statement. 


* It is not the name of a variable but its value 
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which is printed. 


In line 170 the program is terminated by the statement END. 


Exercises: 


1. Modify the program, so that numbera is assigned the 
value §. 


2. Iry other values for numbera and numberb. 
=. Add a new line to the program: 

105 PAGE 

What effect does this order have? 


4. Place a semicolon (3) at the end of each of the lines 
140 - 160. RUN the oroaram, and note that 3 yields 
one space between items. 


S.- Try to write a program which computes the average of 
three numbers. Be sure that the printout 1S correct. 


THE INPUT STATEMENT 


In the previous examole we saw a program in which the 
comouter did a numerical caiculation and printed out the 
result on the screen. In order to compute the average of 
two numbers, it was necessary to change two iines in the 
program when each new average was to be caiculated 


Now we will see how to change these iines once and for ali 
so that the program can compute the average of any two 
numbers we choose without changing the proaram every time. 


Program 2: 


Frogram 2 1s avaliable on the demo diskette. You can copy 
it into working memory by using the oraer load "Program 
2", or type it in as follows: 


new 
auto 100 


0100 // computing an average 

0110 INPUT "Enter the 1. number ": numbera 
0120 INPUT "Enter the 2. number "st numberb 
0130 average: = (number a+numberb) /2 

0140 PRINT "The average of the numbers" 
01350 PRINT numberas; "and" s;numberb 

0160 PRINT "is"; average 

0170 END “end!" 


Check that the program is correct, then execute it using the 
command RUN. 


List the program and notice how using the INPUT statement 
allows the program variables to be assigned a value while 
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the program is being run. 


Thus it is not only possible to print out variable values 
rom a program, but also to read values into a program. 


Notes: 


* Frogram execution is stopped by an INPUT statement 
until the user responds. In Program 2 it is necessary 
to tvpe in a number in response to each INPUT statement 
followed by a <RETURN>. 


* The text of the INPUT statement must be terminated by a 
colon is) before the variable. AI1l other characters 
will result in error messages. 


Exercises: 


1. Add a line with the order FAGE to the program, so the 
screen is cieared at the beginning of a run. 


=. It is also possible to send the output to a printer, if 
available. 


Add the lines 


135 SELECT OUTPUT “lps” 
165 SELECT OUTPUT "ds: " 


Run the program again and see what happens. 


Line 135 directs the output to the printer, and line 
165 brings output back to the display screen. 


3. Write a program which computes the average of 3 
numbers. The numbers should be read in using INFUT 
statements. 


CIRCLES 


The output from a program can also be in the form of a 
drawing. The next program draws circles. 


Program 3s 


new 
auto 100 


0100 // circles are drawn 

0110 PAGE 

0120 INPUT “Enter the 1. radius ": radiusa 
O130 INPUT "Enter the 2. radius ": radiusb 
0140 sumradius: #radiusa+r adiusb 

0130 

0160 USE graphics 

0170 graphicscreen (1) 


Chapter 3 - -51 - PROGRAMMING 


0180 circle(160,100,radiusa) 
0190 circle(160,100,radiusb) 
0200 circle(160,100,sumradius) 
0210 

0220 WHILE KEY$=CHR#(0O) DO NULL 
0230 END 


Check the program to be sure it 1s correct. then run it. 


The program consists of an input section and a calculation 
section which is separated from the printout section by the 
empty line 150. Empty lines can be useful for separating 
various parts of a program to make the program structure 
clearer. 


Lines 140 and 170 are necessary to prepare the computer for 
doing graphics. 


Lines 180-200 draw 2 circles all of which have their centers 
at screen coordinates (160,100), i.e. about in the middle of 
the screen. 


The radii of the three circles 15S apparent in lines 120-140. 
If the radius exceeds 99 units, the circle will overlap the 
edae of the screen. 


The statement in line 220 is described in Chapter 2. Its 
purpose is to keep the graphics screen visible until the 
user presses any key. 


The function KEY¢ is useful for reading in characters from 
the keyboard while a program is running. We will treat this 
#unction again later. 


Note: 


It may turn out that the "circles" look more like egqaq-shaped 
curves than circles. This Dhenomenon is due to the 
adjustment of the screen displays height/width ratio. If an 
adiustment is availiable, you may wish to make use of it so 
that circles appear correctly on the screen. 


Exercises: 
1. Correct the program so that the third circle is drawn 
with a radius equal to the difference between the two 


radii. You should also change the name of the variable 
sumradius! 


2 Experiment with the use of other arithmetic operations 
in line 140. 


3. Move the centers of the circles. 


4. Add instructions so that more circles with other radii 
and centra are drawn. 


5. The center of the circles can also be read in as an 
input statement. 


For example add the line: 
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135 INPUT "Centers X,Y = “8 xc,yc 
Correct lines 180-200 to: 


180 circle(xc,yc,radiusa) 
190 circle(xc,yc,radiusb) 
200 circle(xc,yc,sumr adius) 


Run the program. 


Note that it is necessary to respond with two values 
separated by a comma (,) in the new INPUT statement. 


6. The circles can be filled with colors. Use the order 
fill(x,y) to do this, where (x,y) must be the 
coordinates of a point inside the closed figure which 
is to be colored in. 


For example if Program 3 is extended with the lines: 


202 pencolor (2) 
204 £111¢160,100) 


the innermost circle will be colored red. Try it! 


7. Try to color other regions ot screen by changing the 
coordinates in line 204. 


For example change line 204 to: 
204 £111 (0,0) 
What happens”? 
8. Now try to color other areas on the screen. Change the 


number in the pencolor order in line 202 to employ 
other colors. See the color code table in Appendix B. 


PROCEDURES I 


When writing extensive COMAL programs, it is particularly 
important to make use of procedures: 


A procedure is a "Subprogram" which can be called from the 
main program or from another procedure. It can perhaps best 
be illustrated by means of some examples. Program 4 is 
available on the demo diskette (and tape), or it may be 
typed ins 


Program 43 


new 
auto 100 
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0100 //filled circles and squares 
0110 start ‘graphics 

0120 draw’ square(10,10,300, 180, brown) 
0130 draw ’circle(160,100,70, yellow) 
0140 draw ‘square(100,50,50,50,purple) 
0150 draw ’circle(125,75,20,orange) 


0170 WHILE KEY$="""DO NULL 
0180 END 


0210 PROC start graphics 
0220 USE graphics 

0230 graphicscreen (1) 
0240 browns: =8 

0250 yellow: =7 

0260 purples =4 

0270 orange: #10 

0280 ENDPROC start graphics 


PROGRAMMING 


O300 PROC draw square (xmin,ymin,xside,yside,color) 


0310 pencolor (color) 

0320 moveto (xmin,ymin) 
0330 draw (xside,0O) 

0340 draw(0,yside) 

O350 draw (-xside,0) 

0360 draw (0,-yside) 

0370 xpoints =xmint+. S#xside 
0380 ypoint: #ymin+. S*#yside 
0390 paint (xpoint, ypoint) 
0400 ENDPROC draw’ square 
0410 


0420 PROC draw’‘circle(xcenter ,ycenter ,radius,color) 


0430 pencolor (color) 
0440 circle (xcenter ,ycenter ,radius) 
0460 ENDPROC draw’circle 


Run the program: afterwards we'll take a look at how the 


program works. 


Program 4 consists of: 


The main program (lines 100-180) 
Three procedures: 
start ‘graphics (lines 210-280) 
draw’ square (lines 300-400) 
draw’circle tlines 420-460) 


Notice that a procedure is called by its name. 


followed by parentheses with a list of parameters to be 


transferred to the procedure. 


The procedure itself is built up as follows: 
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PROC <name> (<a>,<b>,<c>,...) 
<statement 1> 
<statement 2> 


ENDPROC <name> 


Recall that sharp brackets < > around a word 

mean that the word and the brackets can be re- 
placed by names or statements of the users choice: 
E.g. <name> could be replaced by the name 

start ‘graphics, printout or something else 
describing the purpose of the procedure. The no- 
tation <statement no> stands for a legal COMAL 
statement. 





The main program consists of a comment line foliowed by 3 
lines which all call procedures. 


In line 110 the main program just calls the procedure with 
the name start ‘graphics, and the computer proceeds to 
execute the statement in this procedure. 


When the computer has carried out the statements in the 
procedure, it returns to the main program and goes on to the 
next line. 


In line 120 the procedure with the name draw’square is 
called. In this case it 15 not only called Dy name but also 
with a pair of parentheses containing some numbers. The 
numbers are separated by commas (,). 


There must be exactly just as many numbers in the call as 
there are variables in the parentheses following the 
procedure name. 


draw’square(1i10O ,10 ,300 ,180 ,brown) 
PROC draw ‘square (xmin,ymin,xside,yside,color) 


Notes: @ 


* The variable brown has the value 8. It received that 
assignment during the execution of the procedure 
start ‘graphics. 


* During the execution of draw’square the procedure 
will use these values: 


xmins 10 

yminer #10 

xsider=300 
yside:=180 

color: =brown (3:8) 


* Now the computer can carry out the instructions in the 
procedure draw’square, for the values of all 
variables are now available. 
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* The procedures draw‘square and draw’circle consist 
of a sequence of graphics orders. Use the index to find 
detailed descriptions of these orders. 


*# Next the procedure draw'’square computes the midpoint 
of the square in lines 370 and 380. 


* When the computer has completed execution of the 
procedure draw’square, it returns to the next line in 
the main program. 


* In line 130 the procedure draw’circle is called then 
executed. 


* In lines 140 and 150 the procedures are called again, 
but this time other parameter values are used. 


* A procedure can be called many times with various 
parameter values if desired. This is one of the qreat 
advantages of using a procedure. 


Exercises: 


1. Try to move the circles and squares around the screen 
by changing the two first numbers in the procedure 
calls. These numbers stand, respectively, for the 
center of the circle and the lower left corner 
coordinates of the square. 


For example try moving the last square and circle into 
the middle of the screen: 


140 draw‘ square (135,75,50,50,purple) 
150 draw’circle(160,100,20,brown) 


2. The lengths of the sides of the squares can also be 
changed. Change the circles’ radii. 


3. Add other colors. See the color codes in Appendix B. 

4. Other circles and squares can be drawn by adding new 
program lines to the main program containing procedure 
calls. Try it. 

3. Try writing a procedure yourself which can draw a 


triangle and fill it up with a color. Add a program 
line which calls your procedure. 


COMAL AND TEXT 


The next example, Program 53, 1s also composed of a main 
program which calls two procedures: 


Main program (100 -— 160) 
Procedure read ’in (190 - 260) 
Procedure print ‘out (280 -— 460) 


Before we enter this program, try it out and study it, we 
must be familiar with the concept of a string. 
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A string constant is a text enclosed in quotation marks. 
E.g. “John", "billing code" and “he has 7 seals". 


So far all the variables we have worked with have been 
number variables. It is also possible to define variables 
which contain sequences of letters, special characters and 
digits. Such variables are called string variables. 


String variables can always be recognized because they end 
with a dollar sign ($). Examples of string names are: 


names, city#, countrys 


When a string is to be assigned a value, a deciaration 
statement must occur early in the program to assure that 
enough room is reserved in memory for the string. This is 
also refered to as dimensioning the string variable. 


Examples: 
DIM name$ OF 20 (room for up to 20 characters) 
DIM city$ OF 25 {room for up to 25 characters) 
DIM countrys OF 40 {room for up to 40 characters) 


Now the string variables may be assigned text values (strina 
contants): 


names:="Jonathan Doe" 
city$: ="London" 
country$:="Engl and" 


Notese 


* Text must always be enclosed between quotation marks 
Gada 


* The text need not be as long as the maximum space 
specified in the declaration statement. 


* A text variable can contain both large and small 
letters, spaces, digits and certain special characters 
C2 SK?! 8S%' 4-25). On the Commodore 64 it can also 
include the graphics symbols. When we refer to 
characters we mean any of the above. 


In Program 3 we will practice the use of procedures and 
learn more about strings and string variables. In addition 
we will also try using the semigraphics characters of the 
computer. They can be seen on the front side of most keys. 
See Appendix D for more about the use of the keyboard. 


Pay particular attention to the procedure print ‘out if you 
will be typing in the program instead of reading it from the 
demo diskette or tape: 


* Line 310: 2 spaces and 36 <C= o> characters. 


* Line 320: 2 spaces, i <Cm j>, 
54 spaces and 1 <C= 1> character. 


* Line 400: 2 spaces and 36 <C# u> characters. 
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(NB: <C= o> means: hold down the Commodore key, while 
pressing the o-key.) 


Program Sz 


new 
auto 100 


0100 // read’in and print’out of text 
0110 DIM names OF 25 

0120 DIM fromt OF 25 

0130 DIM texts OF 30 

0140 read’in 

0150 print’ out 

0160 END 


0190 PROC read’‘in 

0200 PAGE 

0210 PRINT "Write a message: " 

0220 INPUT “The letter is to ": names 

0230 INPUT “The letter is from ": from$¢ 
0240 PRINT "The message can fill one line." 
0250 INPUT "Start heres": texts 

0260 ENDPROC read ’in 


0280 PROC print ‘out 

0290 PAGE 

0300 PRINT 

0310 PRINT ty SS TT ELIE 10 
0320 PRINT " a” 
0330 PRINT " i” 
0340 PRINT "“ ‘" 
03350 PRINT " ‘" 
0360 PRINT " a" 
0370 PRINT " " 
0380 PRINT " i" 
0390 PRINT " i" 
0400 PRINT " . 
0410 PRINT AT 4,6: "To "s3names$ 

0420 PRINT AT 6,6: texts 

0430 PRINT AT 8,6: "Best regards" 

0440 PRINT AT 9,6: froms 

04350 CURSOR 20,1 

0460 ENDPROC print ‘out 





In the main program the first statements declare the 
variables names, fromt and texts. Then the procedure 
read’in is called. It allows for the input of values for 
the text variables. 


When the read-in procedure is completed, the computer 
returns to the main program. In the next line execution 15 


directed to the procedure print ’out, which prints out the 
message inside a frame. 


Notes: 


* A new version of the PRINT statement is used: 
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PRINT AT <line>,<column>. 


E.g. in line 440, where the from$ text is specified 

to begin on line 9, in column 4&4. This syntax makes it 
possible to place text or numbers anywhere on the 
screen. 


Line 450: CURSOR 20,1 


CURSOR <line>,<column> places the cursor anywhere on 
the screen, but no message is printed. 


* See also INPUT AT, which is used in Program 10. 


Exercises? 


i. 


ei 


Run the program a few times with different messages to 
get an idea of how the program operates. 


If a printer is available, one can get a hard copy of 
the text screen by pressing <CTRL PF: 


When the program has finished running, and the text is 
ready on the screen, press P while holding down the 
<CTRL>-key. 


Try revising the program so that text variables can be 
read in and printed at various positions on the screen. 


es cr mre tes cre cer ce cree ee cee ce mr rr cr ee eee ee rr ce re ty ee ee re es ee em ee ee ee ee we ee en we re we oe ee 


Here is a BRIEF REVIEW of the foregoing intor- 

mation on strings and texts: e 

1. A computer can work with numbers or with words. 
This is done using number variables and text 
variables. Text variables can be recognized 
because they always end with §&. 


2. Variables can be given values: 


* by assignment statements 3:2 
* in parenteses in procedure calls & 


3. Text can be written on the screen by means of 
PRINT statements. (It can also be done in 
other ways, e.g. in the text segment of an 
INPUT statement, as we have seen.) 


4. Drawings can be made on the screen using 
graphics orders from the graphics packages 
(use graphics or use turtle), or by means 
of the semigraphics character set, which is 
shown on the front of the keys. 


9. If a program is more than a few lines long, it 
should be composed using procedures. A 
procedure is a ‘sub-program’ which can be used 
many times from the main program or from other 
procedures. We'll be studying more on the use 
of procedures later in this chapter. 
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BRANCHING. CONDITIONAL EXECUTION 


The computer can also distinguish between expressions, which 
are true or false. Such expressions are cailed 


logical expressions. Some examples: 


722 is a logical expression, which both we and the 
computer would consider false. 


23<354 is a true logical expression. 


Whether or not the liogical expression number>10 is 
true or false can not be determined before we know 
the value number. 


COMAL contains the two logical constants TRUE and FALSE, 
which have numerical values 1 and O respectively. 


In the following examples we have illustrated how the 
computer can be made to execute various statements according 
to whether a logical expression 1s true or false. 


Program 6: 


new 
auto 100 


0100 // find the maximum 

0110 PAGE 

0120 PRINT "The maximum of two numbers: " 
0130 PRINT 

0140 INPUT “Write the 1. number ": a 
01350 INPUT "Write the 2. number ": b 
0160 

0170 maximum: =a 

0180 IF maximum<b THEN maximum: =b 


0190 
0200 PRINT 
0210 PRINT "Maximum is “3s maximum 
0220 END 
The new construction occurs in line i180: IF - THEN 


It 15 an example of a branch, also called conditional 
execution. In this case the construction means: 


"IF the variable maximum is less than the variable b, 
THEN maximum is set equal to b". 


The computer evaluates the logical expression maximum<b. 


IF it is true, the computer will execute the statement 
following the order THEN. This is often described by 
saying: the condition between IF and THEN must be 
fulfilled. 


If the condition is not fulfilled, the computer simply 
proceeds on to the next program line. 
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It is often the case, however, that it is desirable to have 
several statements executed when the condition is fulfilled, 
while other statements should be executed if it isn’t. This 
situation is handled in COMAL by using a new structure: 


IF — THEN - ELSE - ENDIF. 


IF <condition> THEN 
<statement 1> 
<statement 2> 


ELSE 
<statement a> 
«statement b> 


ENDIF 


Lines 170 — 180 in Program 6 could thus also be written as 
follows using this [IF-constructions: 


170 IF a<b THEN 
172 maximum: #b 


174 ELSE 
176 maximum: a 
180 ENDIF 
Program 7: 
new 
auto 100 


0100 // right or wrong 

0110 DIM texts OF 10 

0120 PAGE 

0130 PRINT "Guess my numbers 1, 2 or 3" 
0140 INPUT "Try your luck ": answer 
01350 

0160 RANDOMIZE 

0170 my ‘number: *®RND (1,3) 

0180 

0190 IF answer=my number THEN 

0200 text: ="CORRECT" 

0210 ELSE 

0220 text$: ="WRONG" 

0230 ENDIF 

0240 

02350 PRINT 

0260 PRINT "My number was “smy ‘number 
0270 PRINT "The guess was "; answer 
0280 PRINT 

0290 PRINT “So the guess was “stext$ 
O300 END 


Notes on this programs 


* Lines 190-230: Note the IF - THEN - ELSE —- ENDIF 
structure, described earlier. 
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* Lines 160-170: the computer is able to generate a 
random number with the orders RANDOMIZE and RND: 


RANDOMIZE causes the computer to position a pointer at 
a "random" position in an array of random numbers. 


In my ’numbers®RND(1,3) the variable my’number is 
set equal to a random (RaNDom) value 1, 2 or 3. 


The range of numbers can be changed. €.g. RND(-10,10) 
will randomly generate one of the numbers: -10,-9,- 
Boas Oye eee Be 7510. 


Exercises: 


1. Experiment using other number ranges in the RKND 
function. 


bh 


- Try removing the statement RANDOMIZE and run the 
program several times. What happens”? 


THE CASE STRUCTURE 


If one must distinguish among many conditions at the same 
time, then tne CASE structure is advantageous to use. It 
is built up as follows: 


WHEN x1i.value> 
<statement la, 
<statement ib> 


WHEN <2.value,s 
<statement Za> 
<statement 2b> 

(additional WHEN-values) 


OTHERWISE 
<statement a> 
<statement b> 


ENDCASE 


If e.g. <variable> equals <2.value>, then execution proceeds 
in the corresponding segment of instructions: <statement Z2a> 
- <statement 2b>, etc. Then execution continues in the line 
after ENDCASE. 


If <variable> does not equal any of the given WHEN values, 
then execution continues with the statements in the 
OTHERWISE segment. OTHERWISE and the statements in the 
corresponding segment are optional. 


This structure is used in the following example, where one 
can choose among several different exercises in computation. 
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Each exercise 1S given in a procedure. An answer to an 
exercise is evaluated in the procedure result, which is 
therefore called from each exercise-procedure: 


Main program —- exercisel - result 
exercise2 — result 
exercises — result 
exercise4 - result 


Program 8: 


new 
auto 100 


0100 // Computation exercises 

0110 PAGE 

0120 PRINT “Choose an exercise: " 

0130 PRINT 

0140 INPUT “Which number (1 - 4) ": number 


0160 CASE number OF 
0170 WHEN 1 

0180 exercise! 
0190 WHEN 2 

0200 exercise2 
0210 WHEN 3 

0220 exercises 
0230 WHEN 4 

0240 exercise4 
0250 OTHERWISE 

0260 PRINT "You have chosen an incorrect number." 
0270 ENDCASE 


0290 END 


0320 PROC exercisel 

0330 PRINT 

0340 INPUT “INT(7.34+3.2 DIV 2) = ": answer 
0350 correct:@#INT(7.3+3.2 DIV 2) 

0360 result (correct ,answer ) 

0370 ENDPROC exercisei 


O390 PROC exercise2 

0400 PRINT 

0410 INPUT “3-30/2+12 = "3: answer 
0420 corrects: #3-30/2+12 

0430 result (correct , answer ) 

0440 ENDPROC exercise2 


0460 PROC exerciseS 

0470 PRINT 

0480 INPUT "4.2542.5/35#2 = ": answer 
0490 corrects: #4, 2542. 5/S5#2 
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0300 result (correct, answer ) 

0310 ENDPROC exerciseS 

0320 

O3S30 PROC exercise4 

03540 PRINT 

0350 INPUT “34 MOD 10-235 = ": answer 
0360 correctr#=34 MOD 10-2#5 

0370 result (correct, answer ) 

O380 ENDPROC exercise4 

0390 

0600 PROC result (correct, answer ) 

0610 PRINT 

0620 PRINT “The answer is: "s; answer 
0630 PRINT “The correct answer is: "jcorrect 
0640 PRINT 

04650 IF answer=correct THEN 


0660 PRINT "You answer is right!" 

0670 ELSE 

0680 PRINT "Wrong. Please try again..." 

0690 PRINT "Check Appendix Cz: calculating with COMAL. " 
0700 ENDIF 

0710 


0720 ENDPROC result 
Notes: 


A procedure may be called from another procedure, as well as 
from the main program. For example result is called from 
the exercise procedures. 


Exercises: 
1. Try responding to some of the exercises in the program. 
2. Create a new exercise 3S: 


Write a procedure exerciseS. 
Add the new WHEN value in the CASE structure. 
Remember to change the INPUT statement. 


> Write a program which prints out different messages. 
The messages should depend on the value of the variable 
which is entered. 


REPETITION AND LOOPS 


Repetition is one of the fundamental building blocks of 
programming. The computer is uniquely well-suited for 
repeating operations over and over again. In COMAL there 
are several different statements which can accomplish 

repetition. These statement combinations are classified as 


loop blocks or simply as loops. 





The first example shows how the computer be made to repeat a 
set of orders a certain number of times: 


Repeat <these statements> 100 times. 


This is accomplished with a FOR —- ENDFOR loop: 
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FOR <no>:=<start> TO <end> DO 
<statement a> 
<statement b> 


ENDFOR <no> 


Statements a, b and so on are repeated (<end>—<start>+1) 
times: 


the first time <no> equals <start> 
the second time <no> equals <start>o+l 
the third time <no> equals <start7+2 


the last time <no> equals <end> 


Program 9:3 


new 
auto 100 


0100 // investigation of RND 
0110 USE graphics 

0120 graphicscreen (0) 

0130 wrap 

0140 window(0,1000,-10,10) 

0150 moveto(1000,0);3; drawta(0,0) 
0160 

0170 FOR nosz#0 TO 1000 DO 

0180 number : ®RND (-10, 10) 

0190 moveto(no,0O); draw(0O,number ) 
0200 ENDFOR no 

0210 

0220 WHILE KEYS#CHRS(O) DO NULL 
0230 END 


The program illustrates graphically how "random" numbers 
generated by the RND function can be distributed. Notice 
the loop block: 


line 170-200: the FOR — ENDFOR statement. 
The loop is repeated 1001 times. 


The statement can be extended using the STEF parameter: 
FOR <no>s=<start> TO <end> STEP <steps> DO 

where STEF causes <no> to take on the values: <start?, 

<start+steps>, <start+Z%*steps> etc. The loop ends when 


<no> exceeds <end>. 


If the STEP parameter is left out (as we have done so far), 
then STEP is automaticaily set equal to 1. 


In addition to the graphics statements which we already have 
become acauainted with, the program contains some new 
statements. Their use is explained in detail in Chapter 5 
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in the section on graphics. 


Finally we can take a closer look at the statement in line 
220. Here is also an example of repetition: 


In the WHILE - DO statement, the computer checks the 
keyboard again and again, until any key is activated. 


The keyword KEY$ is a function which outputs the last 
character which was sent from the keyboard. If no key has 
been pressed, then "" (ASCII code 9) is returned. KEY 
will thus continue to return "" until any key is pressed. 


while <no key is pressed> do <nothing>s 
WHILE KEYS=CHRS (0) DO NULL 


But the most common use of the WHILE statement is ina loop 
block extending over several lines: 


WHILE <condition> DO 
“statement as 
<statement b> 


ENDWHILE 


If the <condition> between WHILE and DO is fulfilled, the 
computer goes ahead with statements a, b, etc. These 
statements are executed one after the other until something 
occurs in the statements so that the condition is no longer 
fulfilled. Then program execution jumps from the WHILE-DO 
line to the line just after ENDWHILE. 


See the word WHILE in the index to find a more detailed 
description of how this construction can be used. 


Another often encountered loop structure is the REFEAT - 
UNTIL construction: 


REPEAT 
<statement a> 
<statement b> 


UNTIL <condition> 


The statement list is repeated until the’ <condition> is 
fulfilled. 


In the next example, Program 10, this type of loop 
determines how long the user can continue to guess the 
letters ina “secret" word. The example also illustrates 
the use of strings in COMAL. 


The program structures 


The main program — select ‘word 
—- new ‘letter 
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Program 10: 


new 
auto 100 


0100 // word guessing 

0110 PAGE 

0120 select ‘word 

0130 number: #0 

0140 

0150 REPEAT 

0160 number : number +1 

0170 new letter 

0180 UNTIL answer $==remember $ 

0190 

0200 PRINT AT 20,53: "Now finished" 
0210 PRINT AT 21,5: numbers; "letters have been used." 
0220 END 


0250 PROC select ’word 

0260 DIM names OF 20, letters OF 1 

0270 DIM used OF 200 

0280 INPUT “New word: ": names 

0290 lengths #LEN (name$) 

0300 DIM answers OF length, remembers OF length 
0310 answer $3 2" ----------------------- . 

O330 used$:;="" 

0340 PAGE 

0350 PRINT “GUESS THIS"“slengths; “LETTER WORD" 
0360 PRINT AT 8,5: “Words: "3; answers 

O370 ENDPROC select ‘word 


0390 PROC new‘ letter 
0400 INPUT AT 10,5,1: “New letter "s: letters 
0410 used$: sused$+letters 


0430 position: letters IN names 
0440 IF position>O AND position<=length THEN 


0450 answers (position) :=letter$s 
0460 name$ (position) :="¢" 

0470 ENDIF 

0480 


0490 PRINT AT 10,17: " " 

0500 PRINT AT 8,5: “words: "; answers 
0310 PRINT AT 12,1: used$ 

03520 ENDPROC new’ letter 


Lines 150-180: the REPEAT — UNTIL loop: 


When the user has the answer which the computer remembers, 
the program continues in line 190. 


Notes: 


# Line 160: the variable number occurs on both sides of 
the assignment operator :#. This is legal (‘and often 
done). Remember how the assignment operator works: 
First the expression on the right hand side of the sign 
is computed. Then the variable on the left side is 
assigned the value computed. 
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* Line 400: INPUT AT 10,5,1 means that the INPUT 


statement must begin on line 10, column 3, and 

there must be room for 1 character in the the answer 
field. Try to write several answers to see how the 
program works. Try changing 1 to e.g. $3, and run 
the altered program. 


The branch construction IF —- ENDIF begins in line 440 
and extends over several lines, ending in line 470. 


Line 440: AND is an example of a logical operator. 
It requires that both conditions in the IF -—- THEN 
statement must be fulfilled. 


Note particularly about strings: 


* Line 290: The LEN function indicates how many 


characters are included in the word. This is how the 
length of the word is determined. 


Line 300: It is possible to use variables in DIM 
statements. 


Line 410: Words can be ‘added together’ using the + 
character. This process is called concatenation of 
strings. 


Example: “cat"+"fish" yields the word “catfish". 
Line 430: IN is a logical operator which acts on 
strings. It indicates the first position of the first 


character in the search string. 


Examples: “ok" IN "cooking" yields the value 3. 
"i" IN “cooking" gives the value 5. 


If the search string is not contained in the given text 
string, then the value will equal O (zero). 


Examples: “salt" IN "cooking" gives the value O. 
“sing” IN “cooking” gives the value O. 


* Line 450-460: One can select particular substrings ina 


text by using the position of the substring in the 
text. 


Example: LET text#s="cooking" 
text$(3) is the letter “o". 
text$(4:7) is the string “king”. 


In line 460 the letter found is replaced by a charactér 
which never will occur ina word. This is done toa 
allow the same letter to occur more than once ina 
word. In this case the character selected is #@¢. 


ARRAYS. INDEXED VARIABLES 


When you have to work with lots of numbers, it can become 
time consuming to read them all in and give them different 
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names. Sometimes at least 100 variable names may be needed 
when solving one of the following problems, for example: 


* Computing the average of 100 numbers 
* Determining the maximum and minimum of 100 numbers 
* Sorting 100 different numbers 


Large collections of numbers can be handled in COMAL by 
declaring an array using a dimension statement as for 
example the following: 


DIM x (30) 
This statement reserves room for 50 numbers in the 
computer ’s memorv. Each variable will have the same name @ 


x but a different number: 
KCL), (2), KCB) pac ceny X(49), x (350) 


Such variables are also termed indexed variables with the 
number of each variable called an index. 


It is possible (but not common practice) to: each of the 
indexed variables a value using an assianment statement: 


1)3=23 
x (2)8=71 
x (3) 8=-12.45 


x (49) 3: =6 
x (50) :=0. 852 


In the next program example we will work with indexed 
variables which are assigned values by means of an INPUT 
statement. 


The program draws line segments through the coordinates of a 
number of points. 


Program 11 consists of: ® 


a read-in section (lines 110-220) 
agraphics section (lines 270-300) 


Program i113 


new 
auto 100 


0100 // line segments 

0110 DIM x(30), y(30) 

0120 PAGE 

0130 PRINT "A line is drawn through the points. " 
0140 PRINT 

01350 REPEAT 

0160 INPUT “Number of points: ": number 

0170 UNTIL number >=2 AND number<=50 
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0180 PRINT 

0190 FOR no:#1 TO number DO 

0200 PRINT “Enter x(",no,") yt ",no,")3"3 
0210 INPUT "“"3s x(no),y (no) 

0220 ENDFOR no 

O230 PRINT 

0240 PRINT “Press any key to draw the figure." 
O250 WHILE KEYS=CHR#(0) DO NULL 

0260 

0270 USE graphics 

0280 graphicscreen (0) 

0290 moveto(x(1),y(1)) 

O3O0O FOR nos:#2 TO number DO drawto(x (no) ,y(no) ) 
O310 WHILE KEY#=CHR#(0O) DO NULL 

O320 END 


Notes: 


* Line 110: Room is reserved for 509 pairs of x- and y- 


coordinates. 


* Line 160: The program inquires in an INFUT statement 
how many sets of coordinates to be read in. The INFUT 
statement is included in a REFEAT - UNTIL loop which 
also assures that at least 2 pairs are entered. (A 
line can’t be drawn if only one point has been 
entered.) 

* Lines 190-220: the coordinate pairs x(1),y(1) 
x(2),y(2)... xX (number) ,y(number) are entered in a FOR 
—- ENDFOR loop. 

* In line 270-300 the figure is drawn using graphics 
statements. 

Exercises: 

1. Use the program with a few points. 

z. Add a iine in the program which wiil piace a smali 
circle around each point. For example trv 
circla(x (no) ,y(no) ,3). 

3. Write a program which computes the average of an 
arbitrary number of values. The program should include 
the following sections: 

Enter the number of values. 
Enter the values in the array otf numbers. 
Compute the sum of the numbers. 
Average := the sum/number of values. 
4. Those arrays which we have handled so far have been arrays 


with one index. They are termed one-dimensional arrays. 
In COMAL an array can have two or more dimensions. For 
example: 


DIM bookcase (3,4) 


The variable bookcase is a two dimensional array. 
One can imagine a bookcase with 3 shelves. each with 
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room for 4 items.: 
36 17 -3 72 
89 0.3 14 94 
8 -6 78 66 


For example with the above values for the elements of 
the arrays 


bookcase (2,3) =14 and bookcase (3,1)=8 
Try changing Program 11 so that the one-dimensional arrays 
x€) and y() are replaced by a two-dimensional array 
point(,). You can begin by changing line 110 to DIM 
point (50,2). 


Make changes in lines 290-300 yourself. 


TEXT ARRAYS 


We are not restricted to the declaration of arrays of 
numbers. We can also declare arrays which contain strinas: 


DIM message$(8) OF 20 


Room is made of 8 messages 's, each up to 20 characters in 
lengths: 


messages(1):="Remember the sun." 


messages (8):2"Hurrah! Hurrah! " 


Just as number arrays, text arrays can have two or more 
dimensions. 


The next program illustrates the use of a 2-dimensional text 
array. 


The array 1S declared in line 130: 
DIM person$(50,4) OF 30 


It 1s to be used as an address list for up to SO persons, 
with 4 items of information about each one: 


persons (no,1):="<name>" 

per sons (no,2):="<street>" 

per sons (no,3) :="<town>" 

persons (no,4):="<telephone number>" 


In this program we will also become acquainted with yet 
another way to read in variable values: a DATA statement. 


Information can be stored in DATA statements which can be 
read using READ statements. 


The following statements: 
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number ,item$,x ,points 
17, "doll" ,~346,10 


replace four separate assignment statements: 


numbers: =17 
item$:="doll" 
K8z—-S46 
points: =10 


Notice here that numbers and strinas can be mixed in the 


same DATA 


and READ statements. 


The following program consists of. 


Lines 
tines 


Lines 


120-250: dimensioning and assignments 

270-350: printout of information which agrees 
with the search code 

=BO-S00: DATA statements 


Program 12: 


new 
auto 


0380 
0390 


100 


// address list 
PAGE 
number :=50;3; no: =0 
DIM person$(number ,4) OF 30, text$ OF 30 
DIM found (number ) 
REPEAT 
nor+1 
FOR information:2#1 TO 4 DO READ persons (no,information) 
UNTIL EOD 
number : =no 


INPUT "Search forse ": text$ 
FOR noz#1i TO number DO 
information: =O 
REPEAT 
informations +1 
found (no) :#texts IN persons (no,information) 
UNTIL found(no) >0 OR information=4 


ENDFOR no 

PRINT 

PRINT “Persons whom the search key fits: " 
PRINT 


FOR no:1 TO number DO 
IF found(no) >0 THEN 
FOR informationz:#1 TO 4 DO PRINT person$(no,information) 
PRINT 
ENDIF 
ENDFOR no 
END 
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0400 

0410 DATA "Susan Hansen", “"Lindebakken i3" 

0420 DATA "Silkeborg","06-8417235" 

0430 DATA “Commodore Data","Bijierrevej 67" 

0440 DATA "8700 Horsens", "05-641155" 

0450 DATA “Jan Mogensen","Skovgade 4" 

0460 DATA "1717 Copenhagen", "01-456701" 

0470 DATA "Knud Jensen", "Sneglevej 12 D" 

0480 DATA "2820 Gentofte", "secret" 

0490 DATA “Wesleyan University", "Physics Department" 
0500 DATA "Middletown CT 06457","(203) 344-7930" 


Notes: 


* The READ statements need not be placed together with 


the DATA statements. The first READ order in the 
program begins by reading in the first value in the 
first DATA statement no matter where it occurs in the 
program. (This can be altered. See the discussion in 
Chapter 4 on READ and DATA.) 


In line 180 the function EOD is used to terminate the 
reading process. The value of EOD is O (i.e. 

false), until the last data value is read in. Then 
COMAL sets it eguai to 1 (i.e. true). When the 

UNTIL condition thus is fulfilled, the program 
continues in line 190. 


Exercises: 


1. 


ee 


Try out the program. Try to understand how it 
operates. Trv responding to Search for: with just 
<RETURN:?. Add new DATA statements. 


Replace the values in the DATA statements for others of 
your own choosing. The program can of course also be 
used to file any information you may choose. For 
example you might exchange the variable person$ with 

a new variable item$ which could represent items in 

an inventory. For example: 


item$(no,1):="warehouse" 

item$(no,2):="storage area" 

item$ (no,3):="shelf" 

item$ (no,4):="item" 

Add a line to the program which prints out the 
classification number of the person or item along with 
the other information. 


Add further information about each person in the 
address list: 


DIM persons (number ,5) 
where for example: 


per son$(no,5) 1="<profession>" 
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PROCEDURES I1 


In the section FROCEDURES I we became acquainted with two 
difterent ways of using procedures: 


WITHOUT transfer of parameters 





//main program 
<statements> 


name 


© ~statements-s 


END 

ae 

PROC name 
~statements- 


ENDPROC name 


WITH transfer of parameters 


//main program 
“statements> 

name (4,"Christina”") 
“statements: 


END 

4 

PROC name (number ,text$) 
~Sstatements-s 


ENDPROC name 


If there is a transfer of parameters in parentheses, then 
the number and type must be in agreement: 


eS name(4 ,"John",from,x() ,logo$s) 
PROC name (number ,text$,start,no() ,string$) 


The number and type of the actual parameters in the 
procedure call must correspond to the number and tvpe of the 


formal parameters in the procedure’s parentheses. 


4,"John",from,x(), logos are the actual parameters. 
number ,text$,start,no() ,strings are the tormal parameters. 


If the parameters are in agreement with respect toa numper 
and type, they need not have the same name. 


We have emphasized that procedures should be used when 
building up programs, because: 


* Frocedures can be used again and again in different 
parts of the program. 


* The program will be clearer to read, more logical and 
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easier to grasp if it has been broken down into 
procedures with well-chosen names. 


* Frocedures can be saved in a procedure library on disk 
or cassette tape for use later in other programs. 


There are many ways to use procedures. In the tollowing 
sections you will find an introduction to the extended use 
of procedures and functions: 


* In what ways are they similar? 
* In what ways are they different? 
* How can they be used. 


LOCAL AND GLOBAL NAMES 


In COMAL one must distinguish between global and local 
names. A local variable name —- in contrast to a giobal 
name - is only defined and recognized in a limited segment 
of the program. For example: 





FOR no:#2 TO number DO 
«statements > 


ENDFOR no 


The variable name no is local in the FOR -—- ENDFOR iobop. 
It 165 undefined outside this loop. 


In connection with procedures one also refers to liocal 
names, only recognized within the procedure, and giobal 
names which are recognized throughout the program. In 
general, parameters listed in parentheses after a procedure 
name are iocal. In addition the procedure may contain other 
Global and local parameters. 


The advantage of local names is that they do not inter+tere 
with other parts of the program and vice versa. 


Enter, run and examine the next example with global and 
local variable names. Note the values of the quantities 
which are printed out. 


Program 138 


new 
auto 100 


0100 // local variables 
0110 aseligbs:2i 

0120 PRINT asgb 

0130 local ‘global (4) 

0140 PRINT asb 

01350 END 

0160 

0170 PROC local ‘global (a) 
0180 PRINT asgb 

0190 ENDPROC local ‘global 


In the parameter transfers examined so far we have seen a 
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number of one-way transters from the main program to a 
procedure. In order to permit transfer of local parameters 
from the procedure, the parameters must be declared using 

a REF prefix. The procedure in the following example shows 
how this can be done. 


Program 14: 


new 
auto 100 


0100 PROC minmax(a,b,REF min,REF max) 
0110 // minimum and maximum are found 
0120 IF ac<b THEN 


0130 mins=as max: =b 
0140 ELSE 
0170 minz=bs max:=a 


0180 ENDIF 
0190 ENDPROC minmax 


A main program which uses this procedure might iook like 
this: 


0010 //main program 

0020 t:=23 

0030 s:#-41 

0040 minmax (t-s,t+s,minimum, maximum) 

0050 PAGE 

0060 PRINT “t-s ="st—-ss"og"stt+s ="str+s 

0070 PRINT "Minimum, maximums "3; minimums maximum 


0080 END 
Exercises: 
i. The names are unimportant. Exchange the variable names 


minimum and maximum with a ano b respectively. 

Note that thev have no etfect on the results. (A Change 
like this 1s easiest to make using the command CHANGE: 
change "minimum","a", etc.) 


<=. After a procedure has been typed in and checked using 
the SCAN command, it can be used as a direct order. 


Type the following directiy from the keyboard: 


scan 
minmax (12/7,7/12,x,y) 
print xsy 


Try using other values, and try using other procedures 
as direct orders. 


3. Make the following changes and run the program: 


100 PROC minmax (REF a,REF b) 
185 as@ming bs #max 
and 
40 minmax (t,s) 
70 is deleted 


Note, that the variables t and s change their vaiue 





Chapter 3 - - /6- PROGRAMMING 


in the procedure. 


Now the procedure can no longer be used in the torm 
minmax (67,78) with constants in the call. But it can 
be used in the form minmax(x,y) if the variables x 
and y have been given values in advance: 


scan 
x@12363 y2251 
this=(x+y) /x3 that (x-y) /y 

minmax (this, that) 

print "Minimum, maximums "sthiss; that 


Experiment with the legal as well as the illegal 
version. 


A particularly elegant property of procedures is that they 
can call one another. A procedure can even call itself. 
Such a procedure is called a recursiv procedure. 


The next program shows an example of such a procedure using 
graphics. 


Program 15s 


new 
auto 100 


0100 // concentric filled circles 
0110 USE graphics 

0120 graphicscreen (1) 

0130 

0140 draw’ circle(160,100,100,2) 

0150 

0160 WHILE KEY$=CHR$(0) DO NULL 
0170 END 

0180 

0190 PROC draw’circle(xc,yc,r,color) 
0200 pencolor (color) 

O210 circle(xc,yc,r) 

0220 paint (xc,yc) 

0230 

0240 IF r>10 THEN draw’circle(xc,yc,r-10,color+1) 
0250 

0260 ENDPROC draw‘circle 


In line 240 the procedure draw’circle calls itself until 
r aets too small. 


FUNCTIONS 


COMAL ’s built-in standard functions can be used in 
computations. We have already used standard functions like 
PI, RND, INT, LEN. See Chapter 4 for information on other 
standard functions. 


Just as it 1s possible to define procedures using the 
construction: 


PROC -— ENDPROC 
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you can define your own functions in COMAL using the 
structure: 


FUNC — ENDFUNC 


Procedures and functions have many properties and uses in 
common. The next program shows how functions can be defined 
and used to find the roots of analytical functions. The 
program also employs some standard functions. 


Overview: 
main program (lines 100-350) 
function round (lines 380-400) 
function f (lines 420-440) 


where the functions are built up using the foiliowing 
structure: 


FUNC <name> (<number >) 
<statement a+, 

<statement b> 

RETURN <computed ’expression> 


ENDFUNC <name> 


An understanding of the theory behind the method to be used 
requires some knowledge of mathematics. However this 1s not 
essential in order to use the program or to understand the 
statements which compose it. 


Within the discipline of “informatics” the word algorithm 
is sometimes used to describe a tormula or a means ot 
computation. It 1S an important part of good programming 
practice to provide a complete description of the algorithm 
on which a program is based. The description can be given 
in greater or lesser detail depending upon who will use the 
program. A minimum requirement is of course that the 
programmer must be able to understand it later on, if the 
program must be corrected or revised. 


There are in fact many tragic examples of substantial waste 


of resources, both 1n government and in private industry, 
due to poor documentation of programs. 


Program descriptions 


1. The program searches for roots using the 


midpoint method. 





2. The program is designed to find a solution to the 
equation €(x)@0, where # is a function which is 
continuous in the region of interest. 


3. The user must be able to provide an initial guess of 
two numbers a and b with the property that f(a) 

and €(b) have opposite signs. See the figure which 
follows. If this condition is not fulfilled, the 
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program wili request other numbers. 





The midpoint between a and b is found, and the 
value of the function in this point is determined. 


If the value of the function is sufficiently ciose to 
zero, then the program wili conclude that the midpoint 
15 a root. This approximation to the root will be 
printed, and the program will stop. 


Otherwise the program will continue comparing the signs 
of values of the function: 


If the value of the function in the midpoint has the 
same sian as the value of the function in a, then the 
root which is sought is assumed to lie between the 
midpoint and b. Therefore the midpoint is set equal 
to the new a value as the search proceeds. 


If on the other hand the vaiue of the function ina 
and the value of the function in the midpoint nave 
opposite signs, then there must be a root between a 
and the midpoint. The midpoint therefore becomes the 
new b endpoint. 


The program then returns to step 4. 


In this fashion the interval around the root is 
narrowed down until the root has been found within the 
required uncertainty, or the program is interrupted by 
pressing <STOF>. 


Program 16: 


new 
auto 100 


0100 // solving the equation f(x)#0 

0110 PAGE 

0120 e@rror:=iea-04 

0130 REPEAT 

0140 INPUT “End point values A,B: ": a,b 
0150 UNTIL SGN (f(a) ) =—SGN(F (b) ) 

0160 
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0170 LOOP 

0180 sign’ as =SGN (f(a) ) 

0190 sign’b: #SGN(¢F (b) ) 

0200 xmids#(at+b) /2 

0210 ymids =f (xmid) 

0220 IF ABS(ymid)<error THEN 
0230 PRINT 

0240 PRINT "A solution to the equation ="“sround(xmid) 
0250 STOP 

0260 ELSE 

0270 PRINT “. ‘3 

0280 IF SGN(ymid)=sign’a THEN 
0290 ar=xmid 

0300 ELSE 

0310 be: =xmid 

0320 ENDIF 

O330 ENDIF 

0340 ENDLOOP 

O350 END 


0380 FUNC round (number ) 
0390 RETURN INT (number *10000+.5) /10000 
0400 ENDFUNC round 


0420 FUNC f(x) 
0430 RETURN 3#x#x+2#x—-5S 
0440 ENDFUNC f 


The function €(x) itself is defined in the structure FUNC 
f(x). It is defined here by means of the expression 
S#xX #X+24K—S. Thus the program must tind soiutions to the 
equations 

S#K#X+24X-5 = O 


Experiment with other functions besides this one when trving 
out the program. 


Notes: 


* €& new COMAL loop structure: LOOP —- ENDLOOP 
(continuous repetition) is introduced. 


* Clarity is enhanced by the use of descriptive names. 

* The standard function SGN(<expression>): 
SGN (<expression?>)=1°, if <expression> is greater than © 
SGN(<expression>)=0 , if <expression> equals O 
SGN (<expression>)=-1, if «expression; is less than 0 

* The standard function ABS (<expression>) returns the 
numerical value of the expression. E.g. ABS (-2) 


equals 2. 


* The function round rounds off the expression tor 
number to 4 decimal places. 


E.g. round(3.141593) equals 3.1416 
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If 3 decimal places are required, then 10000 can be 
replaced by 1000 in this procedure, etc. 


There should be a correspondence between the required 
accuracy of the calculation specified by the variable 
error and the rounding accuracy specified in the 
function round by choosing e.g. 10000. At the very 
least no more decimal places than those represented by 
the value of error should be returned. 


Exercises: 
1. Run the program with various functions f(x). 


Test the program first using functions with weli known 
roots e.g. 2x-é. 


Use the program to solve equations which can not be 
solved by means of ordinary analytical methods: 


The equation EXP(x)®x+7 is an exampie of such a 
problem. It is called a "transcendental" equation. It 
can be solved using this program by detining the 
function f to be EXP(x)-x-7. 


=. Functions can also be used as direct orders when thev 
have been SCANed. Iry for example: 


scan 
print round (2. 71828183) 


3. Create a numericai function FUNC average(a,b), which 
returns the average ot a and b. Try it as a direct | 
command. 


4. Write a tunction FUNC vowels(text$) , which counts the 
number of vowels in a given string. Try using it as a 
direct order. Hint: take a look at Program 17 tor 
inspiration. 


STRING FUNCTIONS 


Functions can be used for other purposes than just 
calculating matematical expressions (a job which they of 
course do very well). 


The functions which we have just worked with are numerical 
functions. COMAL can also handle string functions. A 
string function is a function which outputs a string instead 
of a number. Just as the case of string variables, the name. 
of string functions must end with the character $. 


KEYS 1s an example of a built in standard string function 
which 1s already available in COMAL. Others include 
STR#$(327) which changes the numerical constant 327 to 

the string constant "327". 


The following orogram illustrates how you can create your 
own string functions. It consistes of a brief main program 
and the function separates. This string function is 
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designed to separate a string into vowels and consonants. 


Program 17: 


new 
auto 100 


0100 PRINT separate$("COMAL string functions") 
0110 END 

0120 

0130 

0140 FUNC separates (a$) 

0150 // consonants or vowels 

0160 long: =LEN(a$) 

0170 FOR is:#1 TQ long DO 

0180 IF a$(i) IN “aeiouAEIOU" THEN 
0190 aS:eas(i)+a$(l2i-1)+a¢(i+ls:slong?) 
0200 ENDIF 

0210 ENDFOR i 

0220 RETURN a$ 

0230 ENDFUNC separates 


Try this example: 


If aS$:="testing" and izs=2:; then line 190 will act as 
follows: a$:= Va" +> kd + "sting" 


Notes: 
* The vowels are placed in reverse order. 


* COMAL can interpret an expression such as a$(7:6). 
This 1s used in line 196 when i:#long. (‘But note that 
a$(68:6) is undefined.) 


Exercises: 


1. Try out the program to see that 1t works as it should. 
Choose other strinas to test the program. You might 
want to experiment with special cases like "a", 


"Lillilieeeee", “qwrtp" and the empty strina. 


z. Create a string function which reverses the order of 
the letters in an arbitrary string. Try it out! 


=. After having been SCANed a string function can be used 
as a direct command just as a numerical function. For 
examples 


scan 
print separates ("sodapop and icecream") 


4. Create a string function FUNC fillup$ (number ,letter$) 
which prints number of the same letter$. Try it 
out as a direct command: print fillup$(30,"“#"). 
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CLOSED PROCEDURES 


If you want to be completely certain that any name conflicts 
between variable names in procedures and the main program 
will be avoided, then you can CLOSE your procedures or 
functions. When you do so, you make all variable names in 
the procedure or function local. Only those values which 
are given in parentheses after the name of the procedure are 
allowed in or out. 


This is accomplished by using the order CLOSED. For 
example: 


PROC name (number ,text#) CLOSED 


It can be very useful to be able to close a procedure. This 
1S particularly true when you want to save a very general 
procedure in a procedure library and use it in many 
different situations. It can be difficult to remember the 
names of all the variables which were used. By closing the 
procedure you can get around this problem. 


The next program illustrates a general procedure which can 
be used to sort any series of numbers. The numbers will be 
sorted so that they are ordered by increasing value. For 
example 4, 3, 7, ~1 are sorted ta -1, 3, 4, 7. 


The sorting method is called the bubble sort. 


There are many algorithms available tor sorting. For 
example on the demonstration diskette and on the tape you 
will find the program quick.sort. It is a tast and 
efficient sorting program. 


The bubble sort used in Program 18 in not the most 
efficient method, but it 1s interesting and easy ta 
understand: 


Consider the numbers in pairs starting at the beginning of 
the sequence. (You might find it useful to imagine small 
bubbles surrounding these pairs.) If a larger number 
precedes a smaller one, then they will be swapped. Now the 
next pair (the second and third) 1s considered. These two 
numbers are swapped, if the largest number comes first and 
SO on down the sequence. The procedure is repeated until no 
more swaps occur. Here is a brief illustration of the 
process: 


1. run-through: 


43 7 -1 1s changed to 3 4 7 -4t 
KA 47 -1 no change 
3 4 7 -1 is changed to 3 4 -1 7 
2. run-through: 
3 4 -1 7 no change 
3 4-1 7 is changed to 3 ~1 4 7 
oS tL 4 7 no change 
~. run-through: 
3s 7) 4 7 is changed to -1 3 4 7 
-1 3 4 7 no change 
-1 3 4 7 no change 
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On the next run-through there will be no more exchanges. 


main program (lines 100-290) 
procedure print ‘out (lines 320-370) 
procedure swap (lines 390-420) 


procedure bubble’sort (lines 440-610) 


All the procedures are closed. 


Program 18: 


new 
auto 


0100 
0110 
0120 
0130 
0140 
0150 
0160 
0170 
0180 
0190 


100 


DATA 2,4,78,45,23,-2,56,45,199,43 
DATA 3,0,100,34,-19,34,67,88,4,10 


// data read-in 
DIM position(1i100) 
no: =O 

REPEAT 

nots +1 

READ position (no#) 
UNTIL EOD 


PAGE 

PRINT "Unsorted number: " 
print ‘out (no#,position () ) 
PRINT 

PRINT 

bubble ’sort (no#,position()) 
PRINT “Sorted number :" 
print ‘out (no#,position() ) 
END 


PROC print ‘out (total ,number ()) CLOSED 
// total number in sequence number() is printed out 
ZONE 8 
FOR not:=1 TO total DO PRINT number (no#) , 
ZONE O 
ENDPROC print ’out 


PROC swap(REF a,REF b) CLOSED 
// a and b are swapped 
remember:=as3 az:=bs 6b: =remember 

ENDPROC swap 


PROC bubble’sort (total ,REF number ()) CLOSED 
// number () is sorted in increasing numerical order 
IMPORT swap 
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0480 REPEAT 

0490 No’ swap: #TRUE 

0500 FOR no#:#1 TO total-1 DO 

0310 IF number (no#) >number (no#+1) THEN 
0320 no’ swaps: *=FALSE 

0530 swap (number (no#) ,number (no#+1 ) ) 
03540 ENDIF 

035350 ENDFOR no# 

03560 UNTIL no’ swap 

03570 ENDPROC bubble ’sort 


In line 460 of bubble’sort the statement IMPORT is used. 

It can be used to make variables or procedures accessible in 
an otherwise closed procedure. In this case the procedure 
name Swap is made available in the procedure 

bubble ’sort. 


In the main program in iine 7240 the order ZONE 8 is used 
to space the printout in columns. Printout of a row of 
numbers separated by a comma (,) in FRINT-statements will 
be done in columns & spaces wide. 


Notes 


* The DATA statements are placed near the beginning of 
the main program. They are easy to find when cnanging 
to new values. 


Exercises: 
i. Try out the program with the valiues provided. Then trv 


with your own values. You should also try the program 
with special cases like DATA 2 or DATA 3,3,3,3,3,5> 


bh 


. This exercise deals with external procedures: 


If a disk drive is available, procedures can be saved 
on diskette individually. Later on they can be brought 
in to be used in other programs when needed. After use 
they are removed from a program. 


Such procedures are termed external when they are 
avaliable outside program memory, as on a diskette. 


There are two conditions which external procedures must 
fulfills 


a. They must be CLOSED 
b. They must not contain IMPORT statements. 


Now remove all other program lines from program 16 
except for the procedure print ‘out and save 
print’out on diskette as a prg file under the file 
name ext.print ‘out: 


save "ext.print’ out" 
The prefix ext. has been added to distinguish this 
type of file from other information in the disk 


directory. 


Then delete the procedure print ’out from program 
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18, and add a line with a declaration which indicates 
that the program will use an external procedure: 


300 PROC print ‘out (no,position()) EXTERNAL “ext.print ‘out” 


Now run the program, and note that the external 
procedure is fetched from the diskette twice during 
program execution. 


The use of external procedures saves room in memory. 

On the other hand the disk operations take time, so the 
method should only be used for larger programs or for 
programs in which the delay time is not important. 


Write a program which sorts words in alphabetical 
order. 


Only a few corrections of Program 18 are necessary to 
accomplish this task: 


First change the following iines: 


140 DIM t$(100) OF 20 
S10 IF t#(no#) >t$(no#+1) THEN 


Next use the CHANGE order: 


CHANGE “position”, "ts" 
CHANGE "number", "t$" 


Suppiy all the variables in the procedure swap with 
$ signs, and change the contents of the DATA 
statements to words or other text. 


COMAL can still interpret the iogical expression in 
line 3510, because a ‘word’ consists of a sequence of 
Characters each of which has an ASCII value. See 
Appendix A for a list of ASCII codes. 


The computer handles the letters in each word one after 
the other when two words are compared. If the first 
letters of both words are the same, then the next pair 
1S compared, and so on. This aliows an evaluation of 
which word is ‘largest’. For example the word 

“apple" is ‘less than’ “banana", because a comes 
before b in the alphabet, and banana is less than 
baseball, because n comes before. s. 


Be careful when comparing words containing both upper 
and lower case letters. Try some experiments! 


FILE HANDLING 


We have seen how it is possible to save a copy of a program 
on diskette or on a cassette tape using the command SAVE. A 
copy of the saved program can be fetched into the working 
memory later using the order LOAD. 


There are also other means of saving programs and program 
segments. See Chapter 4 under the heading LIST - ENTER - 
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MERGE for more information about this. In Chapter 6 you 
will find a summary of these file operations. 


The next program illustrates one of the many ways in which 
data can be saved. By ‘data’ we mean lists of numbers or 
text or perhaps a mixture of numbers and text. Data can be 
stored ina file. A more complete treatment of the use of 
files in COMAL including numerous examples is found in 
Chapter 6. 





The introductory program which we will consider here 
consists of: 


The main program 

the procedures 

file’numbers (<fileno>,<filenames>,number () , total ) 
fetch ‘numbers (<fileno>,<filename$>,REF number () ) 


The two procedures take care of the jobs of saving numerical 
data on disk or cassette and retrieving the data again. 


The main program is simply a test program which saves some 
numbers ina file, fetches them again and prints them on the 
screen. 


These procedures operate by opening a data stream to or 

trom a region on the diskette. The data stream is 
characterized by the number <fileno;, and the region on the 
diskette is characterized by its «<filename#>. It 1s 
thereafter possible to ‘write’ to the data stream, if it has 
been opened in the WRITE mode, or one can ‘read’ from the 
data stream, if it has been opened in the READ mode. A data 
stream remains ‘open’ until it is ‘closed’. 


Saving data: 
OPEN FILE «<fileno?,<filenamet> ,WRITE 


PRINT FILE <fiieno>: number 


CLOSE FILE <fileno> 
Fetching data: 
OPEN FILE <fileno>,<filenamet>,READ 


INPUT FILE <fileno>: number 


CLOSE FILE <fileno> 


Program 19: 


new 
auto 100 


0100 PROC file ‘numbers (fileno,filenames,number () ,total ) 
0110 OPEN FILE fileno,filenames,WRITE 


Chapter 3S 


0120 
0130 
0140 


0310 
0320 
0330 
0340 
0350 
0360 
0370 
0380 
0390 
0400 
0410 
0420 
0430 
0440 
0450 
0460 
0470 
0480 
0490 
0500 
0510 
0520 
0530 
03540 
0550 
0560 


Notes: 
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FOR is=1 TO total DO 
PRINT FILE filenos number (i) 
ENDFOR i 
CLOSE FILE fileno 
ENDPROC file’numbers 


PROC fetch ‘numbers(fileno,filenames$,REF number () ) 
OPEN FILE fileno,filenames,READ 
iz=0 
REPEAT 
is¢+1 
INPUT FILE filenos number (i) 
PRINT number (i) 3 
UNTIL EOF (fileno) 
CLOSE FILE fileno 
ENDPROC fetch ‘numbers 


// numbers are saved and read in froma file 

DIM number (100) 

PAGE 

PRINT "Enter numbers, each followed by <RETURN>." 


PRINT “Terminate by entering 99999;" 
nos =0 
REPEAT 

nosz+i 

INPUT ""s number (no) 3 
UNTIL number (no) =99999 


nos~1 // the last number is not saved 
PAGE 

FOR is#i TO no DO PRINT number (i): 

PRINT 

PRINT “PRESS ANY KEY TO WRITE TO THE FILE" 
WHILE KEYS=CHRS(0O) DO NULL 


file numbers (2, "@numberdata" ,number () ,no) 
PAGE 

PRINT "PRESS ANY KEY TO FETCH DATA AGAIN" 
WHILE KEYS$=CHRS(0O) DO NULL 

PAGE 


fetch ‘numbers (3S, "@numberdata" ,number () ) 


END 


* If the data are to be saved to a cassette tape. the 


file 


name must be supplemented with the css unit 


indicator: "“"cssnumberdata" 


* Data must be fetched using the same file name as the 
one under which they were saved. The stream number 


need 


not be the same. 


The advantage of saving data in files is that the data need 
not be associated with a particular program as with DATA 
statements. The same data can be used by many different 


programs. 
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Notice especially about file’numbers: In the procedure 
call it is essential to specify the (total) number of data 
elements which are to be saved. 


But note regarding the procedure fetch’numbers that the 
computer will simply stop reading in numbers from the file 
when no data are left. To register this condition the 
function EOF (<fileno>) is very useful. It takes on the 
value TRUE when the file contains no more data, thereby 
fulfilling the UNTIL condition. 


Data can be saved in ASCII-code format by means of the 

PRINT FILE order. The INPUT FILE order must then be 

used to enter the data. This combination can be used both 

with a disk drive and with a Datassette unit. If vou are & 
using a disk drive it will usually be best to use the WRITE 

FILE and the READ FILE orders instead, because data can 

be saved more quickly and more compactly in binary form than 

in ASCII form. 


Exercises? 


1. Try out the program with arbitrary numbers. Change the 
file names and stream numbers. Check for legal stream 
numbers. 


z. Use the program to create a set of data. Use these 
numbers instead of the numbers in the DATA statements 
in Program 18. You will have to delete lines 100-200 
and replace them by lines which read in the numbers 
from one of the data files which we have just worked 
with. 


Write a program which saves strings ina file. Read 
the information from the DATA statments in Program 12 
into this file. Then use this file instead of the DATA 
statements in Program 12. 


2 


ERROR HANDLING 


It 1s important that programs are constructed so that they @ 
do not ‘crash’, if the user does something unexpected. 


One of the most common causes of undesired program 
interruption is the entry of LETTERS in an INPUT statement 
in which a NUMBER is expected. 


In COMAL there is an error handling structure’ which can take 
this problem and many others into account. Note that the 
use of this structure is treated more completely in the 
reference section, Chapter 4. Here we will concentrate on 
the one type of error mentioned above. 


The structure is: 
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TRAP 


(statements in which errors are expected) 


HANDLER 


(statements to be executed in case of an error) 


ENDTRAP 


If an error occurs in the statements between TRAF and 
HANDLER, the computer will jump to the statements between 
HANDLER and ENDTRAF. At the same time an ERR code will be 
aqenerated. The ERR code can be used to determine which of 
the statements in the HANDLER-section should be executed. 


In the next program example an error handling structure has 
been placed in the LOOF -—- ENDLOOF loop which we used 
earlier. This loop assures that the INFPUT-statement wiil be 
executed again if input errors are detected. 


Note the following about the various COMAL ioop-structures: 


* In the WHILE -—- ENDWHILE structure the condition is placed 
right after WHILE at the beqinning of the loop. 


* In the REPEAT - UNTIL loop the condition is placed at the 
end, right after UNTIL. 


* In the LOOF - ENDLOOF structure a condition can be placed 
anywhere inside the loop using the EXIT WHEN command. 
When the condition is fulfilled, execution passes to the 
first statement after ENDLOOF. 


The LOOP —- ENDLOOF structure: 


LOOP 


EXIT WHEN «condition: (or just EXIT with no condition) 


ENDLOOP 


The program consists of a general read-in procedure with 
error handlina and a brief main program used to check out 


the procedure. 


Program 201 


new 
auto 100 


0100 PROC number ‘input (line,pos,dpos,text#,REF number) 
0110 // number-sate input 
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0120 // only <STOP> interrupts program 


0130 
0140 LOOP 
0150 
0160 TRAP 
0170 


0180 PRINT AT line,pos: SPCS(LEN(text$)+dpos);" #*" 
0190 INPUT AT line,pos,dpos: text: number 


0200 

0210 EXIT // if the input is OK 
0220 

0230 HANDLER 

0240 


0250 CASE ERR OF 
0260 WHEN 2 


0270 PRINT AT 24,12 “The number was too big." 
0280 WHEN 206 

0290 PRINT AT 24,1: “A number is expected." 
0300 OTHERWISE 

0310 PRINT AT 24,1: "What happened?" 


0320 ENDCASE 
0330 FOR pausers®=1 TO 1000 DO NULL 


0340 PRINT AT 24,1: SPC#(25) 
03350 

0360 ENDTRAP 

0370 

0380 ENDLOOP 

0390 

0400 ENDPROC number ‘input 
0410 

0420 

0430 // test of input errors 
0440 PAGE 


0450 REPEAT 

0460 number ‘input (10,3,10,"Type in a numbers: “,number ) 
0470 PRINT AT 12,3: SPC#(15) 

0480 PRINT AT 12,3: number 

0490 UNTIL FALSE 

0500 END 


Notes: 


* The statement EXIT orders the computer to jump out of 
the LOOP structure if the input is ok. 


* The string function SPCS$(number of spaces) can be 
useful for clearing part of the screen. 


* Line 180 clears the INPUT field and places a * two 
blank spaces after the end of the fieid. 


Exercises: 


1. Try out the program using both numbers and letters. 
Try pressing <RETURN? with no input. 


<.- The LOOP structure can be replaced by a REPEAT loop. 
The following lines can be used: 
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no’error: =FALSE 
REPEAT 
no’error: TRUE 
UNTIL no’error 


Where should these Lines be inserted? 


3. Replace the CASE error texts the the system error 
message ERRTEXT#: PRINT AT 24,18 ERRTEXTS. 


4. Your final examination: 


The character # in line 180 is a speciai detail. 
What can happen, if this character is left out? 
Experiment ! 


After working through this tutorial chapter you shouid be 
well prepared to continue developing your skill with the 
COMAL programming lanquage. Of course there 16 still much 
more to be learned, and you can run imto situations which 
have not been covered here. 


In Chapter 4 you will find a compiete reterence section 
treating all of the many commands and statements in COMAL. 
In Chapter 4 you will find explanations of each order with 
examples to illustrate its use. 
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COMAL. OVERVIEW 


COMMANDS USED BEFORE AND DURING 
PROGRAM ENTRY: 


NEW - AUTO — RENUM 
NEW 


@ 1S a command which causes the oroaram and the data in 
workina memory to be deleted. Svstem variables are set 
to their initial values. and packages and associated 
variables are also deleted. 


AUTO 


1S a command which sets up automatic line numberina 
during program entry. The range of iegal line numbers 
is: i - 9999. During program entry each line should be 
terminated by oressing <RETURN:;. The svstem will 
automatically print the next line number on the screen. 
AUTO can be disengaged by pressina <RUN/STOP>. If AUTO 
1s engaged again ‘or engaged after manual entry of part 
of a program), automatic line numbering will begin with 
the last line number in the program + 10. 


Examples: 
AUTO Gives line numbering: 10, 20, 30,... 
AUTO 1000 Gives line numbers: 1010, 1020,... 
AUTO 100,2 Gives line numbers: 100, 102, 104,... 
Notes: 

@ Line numbering with intervals of 10 is often 


appropriate. for it allows the insertion of several 
extra lines between existing line numbers. 


If a line number already exists. the number will appear 


in reversed characters to warn the user against 
unwanted overwriting of existing code. 


RENUM 
is a command which provides the program in working 
memory with new line numbers. Renumbering can begin 
from any line in the program. 
Examples: 


RENUM New numberings 10, 20, 30,... 


RENUM 2000,5 New numbering: 2000, 2005, 
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2010, eae @ 


RENUM 3003 4000,10 Line numbers from and including 
300 will be changed tos 4000, 
4010,... 


COMMANDS WHICH ARE USED FOR 
PROGRAM EDITING: 


EDIT — FIND — CHANGE - DEL —- SCAN 
EDIT 


is a command which causes program lines to be printed 
one at a time without indentation. It is particularly 
useful for correction of program lines which take up 
more than one line on the screen. If the LIST order is 
used, some lines made contain unwanted spaces after the 
end of the first line. After editing, pressing 
<RETURN?> will cause the next program line to appear, if 
more than one line edit has been requested. 


Examples: 

EDIT allows editing of all iines, one 
at a time. 

EDIT 130 allows line 130 to be edited. 

EDIT 210-290 permits editing of lines 210 —- 
296. 

EDIT colorcodes lets the user edit the procedure 
colorcodes. 

Notes 


The EDIT command can only be used for printout to the 
screen or to a printer. 


FIND 


is a command used during editing to find a name or text 
segment in a program. When the text segment has been 
found, the system prints out the program line with the 
cursor placed on the first character of the text. 

After possible corrections press <RETURN>, and the 
system will search for the next occurence of the text. 


Examples: 

FIND “John" The system will search the 
entire program for the word 
John. 

FIND 200-500 "John" The system searches for the 


word John in lines 200 - 
500. 
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FIND colorcodes "red" The system searches for the 
word red in the procedure 
colorcodes. 

CHANGE 


1S a command which is used to search for and replace a 
text segment. When the text segment to be changed has 
been found, the system prints out the program line with 
the text segment blinking like a cursor. 


There are now three options: 


1. You can make the change by pressing <RETURN>. 

2. You can edit the line without the automatic change: 
Press the <C=> key. 
Change the line as desired. 
Press <RETURN>. 
The search will be continued. 

=. You can order the search to continue with no chanaes: 
Press nor N. 
The search will continue. 


Press <STOP> to interrupt the CHANGE operation. 


Examples: 

CHANGE “red","“yellow" The search text red 
is replaced by the 
replacement text yellow 
evervwhere in the 
program. 

CHANGE 350-200 "xi", "xstart” The change is made in 
lines 50 - 200. 

CHANGE square “up", "right" The change is made in 


the procedure square. 


DEL 


1S a command which is used to delete program lines. 


Examples: 

DEL 20 Line 20 is deleted. 

DEL 40,200~-280 Lines 40 and 200 °- 280 are deleted. 

DEL printout The procedure printout is deleted. 
SCAN 


is a command which causes the system to run through the 
program in the working memory. This process is also 
called making a prepass. The program structure is 
checked for possible errors, and any error in structure 
is reported. After a SCAN without any error messages, 
approved procedures and functions can be executed 
directly from the keyboard like commands. 
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Examples: 
Program as entered: 


0100 number=#0 

0110 repeat 

0120 print number 

0130 number: +2 

0140 print "You saw some even numbers." 
01350 end 


SCAN 

The system will report: at 150: "UNTIL" missing 

add the line: 135 until number >20 

After a new SCAN the proaram should appear as follows: 


0100 number : =O 

0110 REPEAT 

0120 PRINT number 

0130 number :+2 

0135 UNTIL number >20 

0140 PRINT "You saw some even numbers. " 
01350 END 


OTHER COMMANDS: 
SETEXEC 


is a command which has two distinct formats: SETEXEC— 
and SETEXEC+. 


During the initiation of the system, a SETEXEC- is 
executed. This causes the kevword EXEC to be omitted 
from procedure calls. 


After a SETEXEC+ command EXEC will be printed before 
all procedure calls. 


Examples 


Frogram segment as it would be listed after system 
start—up: 


0100 PRINT “Numbers are read in and printed out." 
0110 read’in 

0120 print ‘out 

0130 END 

0140 

0150 PROC read’in 

0160 INPUT “Write the number: “s number 
0170 ENDPROC read’in 

0180 PROC print ‘out 

0190 PRINT number 

0200 ENDPROC print ‘out 


After SETEXEC+: 
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0100 PRINT “Numbers are read in and printed out. "™ 
0110 EXEC read‘in 

0120 EXEC print’ out 

0130 END 


COMMANDS USED TO CHECK AVAILABLE 
MEMORY AND DISK STORAGE: 
SIZE - CAT - DIR 

SIZE 


is a command which causes the present usage of bytes of 
working memory to be reported. 


Example: 
SIZE System response: 
prog data free 
13501 02466 14747 
CAT 


is a command which causes a cataloque of the contents 

of the diskette to be printet. If several disk drives 
are connected. then the station number can be included 
in the command. 


Examples: 

CAT All file names are listed. 

CAT "t#" The names of all files beginning 
with t are listed. 

CAT "?est??" The names of all files which are & 
characters long and with characters 2-4 
equal to est are listed. 

CAT “2:" The contents of the diskette in the 
second disk drive are listed. The 
second drive must be set up as "device 
9°". This can be done using a jumper 
inside the second drive or by means of 
software. See your 1541 instruction 
manual for more on how to do this. 

Note: 


Pressing the space bar will stop the printout of the 
‘disk catalogue. Pressing it again will allow it to 
continue. <STOP> will end it. 


DIR 


may be used as a command or as a statement. Like CAT 
this order causes the contents of the diskette in the 
drive selected to be printed out. Unlike CAT, DIR can 
be used as a statement in a program if desired. 
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LIST -— ENTER — MERGE - DISPLAY 
LIST 


is a command which is used to print out all or part of 
the program in working memory. It is also used to 
store all or part of a program to diskette or to the 
Datassette tape unit. When this is done, the program 
is saved as a sequential file in ASCII-format. Copies 
of the program which have been. saved using the LIST 
command must be reentered using the ENTER or MERGE 
commands. They can NOT be entered using LOAD. 


Examples: & 
LIST All program lines are printed. 

LIST 200-400 Program lines 200-400 are printed. 

LIST 300- The program is printed from line 300 onward. 


LIST demoproc The procedure with the name demoproc 
is printed. 


If the LIST order is followed by a name in quotation 
marks, then the listing will be done to diskette or 
cassette tape: 


LIST “program name" The entire program is saved 
under the file name program 
name. 


LIST demoproc "lst.demo" The procedure demoproc is 
saved under the file name 
lst.demo. The prefix lst. 
is not essential. It is 
included to remind us that the 
program has been saved by a 
LIST command. 


Notes: © 


The printout of the listing to the screen will proceed 
more slowly if the <CTRL> key is depressed during the 
printout. 


The printout can be stopped temporarily by pressing the 
space bar once. Press it again to continue the 
listing. 


Fressing the <STOP> key interrupts the printout. 


The printout can be directed to a printer, if 
available, with the command list “los" 


If a program line extends beyond a single line on the 
screen, the LIST order will cause it to be split due to 
indentation. Place the cursor on the line in question 
and press <CTRL-A>. The line will be pulled together 
again with no indentation. 
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ENTER 


is a command which fetches a program which has 
previously been saved to diskette or cassette tape 
using the LIST command into working memory. NBs 

ENTER acts differently than MERGE. If there is already 
a program in working memory, ENTER will erase it. 


Examples: 


ENTER “lst.name" The program lst.name is 
fetched from diskette. 


ENTER “csz:lst.Program 3" The program L.Program 3 is 
fetched from the Datassette 


unit. 


Notes 


A program which has been save using the SAVE order can 
NOT be read in again using ENTER. 


MERGE 


1S a command which is used to fetch a program segment 
from diskette or cassette and copy it into working 
memory. The program segment must have been saved using 
the LIST command. 


Examples: 


MERGE “lst.circumference" The program 
lst.circum’ference is 
fetched from diskette and 
added to the existing 
proaram with line numbers 
starting after the end of 
the current program. 


MERGE 1000,5 “lst.start” The program (or segment) 
lst.start is read in and 
added to the current program 
at lines 1000, 1005, 1010... 


Be careful not to 


unintentionally overwrite 
existing program lines. 


DISPLAY 


is a command which lists a program or a program segment 
with NO LINE NUMBERS in the listing. 


Examples: 

DISPLAY The entire program is 
listed to the screen. 

DISPLAY. 20-90 "lps" The program from line 


20 to and including line 
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90 is printed on the 
lineprinter with no line 
numbers. 


DISPLAY sort “dsp.sort” The contents of the 
procedure sort is 
stored on diskette under 
the name dsp.sort. 


Note: 


A program which has been saved on diskette (or tape) 
with the DISPLAY command can not be fetched again using 
ENTER or MERGE. However it can be read in as an 
ordinary sequential ASCII file using the order INPUT 
FILE. 


SAVE - LOAD 
SAVE 


1S a command which saves a copy of the program in 
working memory to diskette or tape in compact binary 
form. A SAVEd program can be fetched later using one 
of the following: LOAD, RUN or CHAIN. 


Examples: 


SAVE “program name" The program in working memory is 
saved to disk under the file name 
program name. 


SAVE "cs:racetrack" The program is saved to cassette 
tape under the file name 
racetrack. 


Notes 


Any program packages which are associated with the 
COMAL program by means of the LINE order are saved 
together with the COMAL program as one file. When the 
program is later entered into working memory, e.g. 
using LOAD, both the COMAL program and the machine 
language package are read in together. 


LOAD 


15 a command which transfers a copy of a program from 
diskette or cassette tape into working memory. The 
program must have been saved earlier by means of the 
SAVE command. The LOAD command deletes any previously 
existing program and all variables from working memory. 


Examples: 

LOAD “program name" transfers a copy of the program 
saved under the file name program 
name from diskette into working 


memory. 


LOAD "cs:" A copy of next program on the 
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tape is fetched into memory via the 
Datassette. 


RUN - CHAIN — CON 
RUN 


1s a command which causes the program 1n working memory 
to be executed. All variables are zeroed and the 
computer begins by examining the program structure for 
possible errors. A program can also be fetched from 
diskette or tape and started automatically using the 
RUN command. 


Examples: 


RUN Frogram execution is started (the 
program is ‘run’). 


RUN “program name" The file program name is 
fetched from diskette and execution 
begins. 
CHAIN 
can be used as a statement or as a command. It fetches 
a copy of a program from diskette or from cassette tape 


and starts it running. Any existing program in working 
memory will be deleted first. 


Used as a command CHAIN “<file name>" works like RUN 
"<4ile name>". 


CHAIN is particularly useful when used as a statement 
in a program. It allows the user to break down a liarge 
program into smaller independent units. 


Examples: 


CHAIN "cs:name" The program name is fetched 
from cassette tape and started. 


Program example: 


INPUT “Choose a program numbers "sno 


CASE no OF 
WHEN 1 

CHAIN “program 1" 
WHEN 2 

CHAIN "program 2" 
OTHERWISE 

CHAIN “program 3" 
ENDCASE 

CON 


is a command which causes program execution to continue 
in an interrupted program. The program may have been 
interrupted by an error, by activation of the STOP key 
or by a STOP statement in the program. While the 
program is stopped, changing the contents of existing 
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variables is permitted. However new variable names may 
not be added, and the program may nat be changed. No 
line may be altered, and no new lines may be added to 
the program while it is interrupted. If this is done, 
execution cannot be continued using the CON command. 


STATUS - STATUSS 


STATUS is a command which causes the system to report 
on the status of the disk operating system and zero the 
error flag. STATUS$ is a string function which 
contains the status report. STATUS performs the same 
operation as PRINT STATUSS. 


Examples 


Right after the system is turned on 
STATUS 

will cause the system to answer 
73,cbm dos v2.6 1541,00,00 


VERIFY 


is a command which can be used to check that the 
program on the diskette or cassette tape (saved using 
the SAVE command) is identical to the program which is 
currently in the working memory of the computer. 


Warnings Take care not to change the program in 
working memory before using VERIFY (spell correctiv!). 


Example: 


VERIFY “test prog" The COMAL svstem reports verify 
error, if the program saved under 
the file name test prog and the 
‘program 1n working memory are not 
exactiy alike. 


COPY -— DELETE — RENAME - PASS 
COPY 


can be used as a command or a statement for copying 
diskette files. 


Examples: 


COPY "old’file","new’ file" The system makes a 
copy of the program 
old’file and saves 
it on the same disk 
drive under the name 
new ’file. 


COPY "“Osprogram 3","1:tprogram 3" The system copies 
program 3 from 
disk drive Os: and 
saves it with the 
same name on disk 
drive is. 
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DELETE 


may be used as a command or a statement to delete files 
on a diskette. 


DELETE "testdata" The file testdata is deleted. 


DELETE "“test#" All files which begin with test 
are deleted. 


RENAME 


is used as a command or a statement to change the name 
of a file. 


Examples 
RENAME “old", "new" The diskette file with the 
name old is assigned the new 
name new. 
PASS 


can be used as a command or a statement to send orders 
to the disk operating system. 


Examples: 


PASS "nO:procedurebib,ai" Formats a new 
diskette on disk drive 
Oo. This diskette gets 
the name procedurebib 
and the identification 
number al. 


PASS "n2:diskname,0O1",9 Formats a new diskette 
on the extra disk drive 
(no. 2) with unit 
number 9. 


PASS "v" Clean house (garbage 
collection): The files on 
the diskette are 
collected and any open 
files are closed. The 
letter v represents the 
word validate. 


Notes: 


There are additional orders which can be transferred to 
the disk operating system using PASS. But there are 
more suitable COMAL-instructions for accomplishing the 
same functions. 
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SELECT INPUT — SELECT OUTPUT 
SELECT INPUT 


may be used as a command or a statement. It causes 
subsequent read-in, which normally would occur from the 
keyboard, to come from the specified sequential ASCII 
file. This read-in can be terminated by pressing the 
<STOP> key, by an END-OF-FILE or by errors in the 
program. At this point input will again be from the 
keyboard. 


INPUT statements, KEY# and inkey$ also receive their 

input from the SELECT INFUT file. The COMAL system x 
interprets this input as if it came from the keyboard © 
and echoes it in the usual manner to the screen. 


If SELECT INPUT is used as a command it can be used to 
redefine the meanings of the function keys. 


SELECT INPUT "kbs" Keyboard input. As 
with the start up or 
restart of the COMAL 
system. 


SELECT INPUT “checkfile" checkfile will be 
read in as if it came 
directly from the 
keyboard. 


SELECT OUTPUT/SELECT 


can be used as a command or as a statement. It is used 
to select the unit to which subsequent output will be 
sent. If one simply writes SELECT, the system will 
automatically add OUTPUT in the program listing after 
the program has been scanned or run. 


SELECT OUTPUT "“ds:" Frintout is sent to the 
screen, as when the 
computer first is started 


= e 


SELECT OUTPUT "lps" Printout is directed to 
the printer. 


SELECT OUTPUT “Orsnamefile" A sequential file with 
the name namefile is 
created on disk drive 
QO, and subsequent 
printout is directed to 
the file. 


Notes: 
SELECT OUTPUT can be abbreviated to SELECT. The 
system automatically adds QUTPUT after a scan or a 


run. 


Frintout will automatically return to the screen after 
the LIST command has been executed. 
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Even if printout is directed away from the screen, e.g. 
to a printer, text provided in INPUT statements will 
Still be directed to the screen. 


COMMANDS FOR SYSTEM START-UP: 

BASIC - SYS to COMAL. 
The BASIC command directs the computer to initiate 
the Basic operating system. The computer can be 
directed back to the COMAL system with the order: 
SYS 30000 


Both orders cause all information in working memory to 
be deleted. 


COMMANDS AND STATEMENTS CONCERNING 
THE USE OF MACHINE CODE PROGRAM PACKAGES 


(See also Chapter 8 on COMAL and programs in machine code.): 
USE -— LINK - DISCARD 
USE 
may be used as a command or a statement to append a 
named machine code program package to the COMAL program 
in working memory. The name of the package is hereby 
made known to the COMAL interpreter. 
The order is used for example to make the built-in 
packages in the COMAL cartridge accessible in a pro- 
gram. See more about how to use packages in Chapter 5. 
Examples 
USE graphics The package graphics is activated. 
LINK 


is a command which fetches a file with a machine code 
package from diskette and transfers a copy into working 
memory. The name of the package can then be made known 
to the program by means of the USE order. 


Examples 

LINK "obj.driver" The object code file with the 
name obj.driver is fetched. 

USE driver The above LINKed file contains 
the package with the name driver, 
which is hereby activated. 

Noter 


A machine code program which is associated with a COMAL 
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program by means of the command LINK is saved 

together with the COMAL program as one file using the 
SAVE command. A later LOAD will automatically fetch 
both the COMAL program and the machine code program. 


DISCARD 


is a command which removes all machine code program 
packages from working memory. 


The COMAL program is not lost, but the interpreters 
name table is only intact again after a RUN or a SCAN 
has been performed. 


STATEMENTS USED DURING READ-IN AND PRINTOUT © 
INPUT -— INPUT AT — KEY$ 
INPUT 
is a statement which reads data into a program during 
execution. After an INPUT statement the system stops 
execution and waits for a user response. The cursor 


flashes at the beginning of the input field. AI1 
responses must be terminated by a <RETURN>. 


Examples: 

INPUT "Total “: number The system awaits 
number as 
response. 


INPUT “What's your name? ": names The system awaits 
a string input. 


INPUT "Position (X,Y) = "s: x,y Several numbers 
can be entered in 
the same INFUT 
statement. 


INPUT "Item number: ": no; A (3) or (,) @ 
after the variable 
name suppresses the 
Carriage return 
after the answer. 


INPUT AT 
acts like INPUT with the added possibility of placing 


the input field anywhere on the 25 lines and 40 columns 
of the screen. 


Examples: 

INPUT AT 4,103s “Number = ": no The input message 
starts on line 4, column 
10. 

INPUT AT 4,7,15: "Name “: texts The input message 


starts on line 4, column 
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7. The input field is 
limited to the 15 
following spaces which 
are protected fram other 
uses. 


Special case: 


A O given as line or column number means current 
value. 


Example: 


INPUT AT 0,0,10: "Town "“s: towns The input message 
starts at the 
present line and 
column, but the 
response field is 
limited to 10 
characters. 


See also INPUT FILE and SELECT INPUT. 


KEYS 


is a function which reads the keyboard input buffer to 
determine the last character activated. If no 
character has been sent, then the function returns the 
value chr$(0O) or ""O"".  Frogram execution is not 


stopped in contrast to the INPUT statement and the 
function inkey$ (in the system package). 


Examples of use: 


WHILE KEYS=CHR$(O) DO NULL The program 
‘hangs’ in the same 
line until the user 
presses any key. 


DIM answers OF 1 
PRINT "Answer yes/no" 


REPEAT The system waits for 
answer$: =KEYS activation of 
UNTIL answers IN “yYnN" y,Y,n or N. 


PRINT -— PRINT AT — PRINT USING —- TAB —- ZONE 


PRINT 


may be used as a command or a statement. It is used to 
Print data on the screen or send it to other output 
devices. If the FRINT line contains several items, they 
can be separated by a semicolon (3). This will cause 

a single space to be printed between each item. If a 
comma (,) is used, the the number of spaces between 

the beginning of each item is determined by the ZONE 
order. During program coding PRINT can be abbreviated 
to 3. 
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Examples: 

PRINT "Results “sspeed; "m/s" text and numbers 
can be mixed in the 
printout. 

PRINT Prints out an empty line. 

PRINT texts 3 The carriage return is suppressed 

by terminating the PRINT line with 
a (3) or a (,). 
PRINT AT 


can be used as a command or as a statement. It makes 
it possible to print.,numbers or text at any character 
position on the screen. Line numbers may range from 1 


- 25, and column numbers from 1 —- 40. 
Examples 
PRINT AT 3,12: “Name is"3; names The printout 


begins in the 3. 
line, column 12. 


Special case: 


A O as line or position number means present or 
current. . 


Examples 


PRINT AT 0,30: "“COMAL" Write on the present 
line, column 30. 


PRINT USING 


can be used as a command or a statement. It is used 
for printing numbers ina well defined format. 


Examples: 


PRINT USING “Price ###4.8#": price The amount is 
written in the 
format determined by 
the # signs and 
the decimal point. 
In this example 
there is room for 3 
digits before the 
decimal point and 2 
digits after it. 


The various PRINT options can be combined: 


PRINT AT 10,13: USING “Speed = 44.44": speed 
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Note: 


If the number is too big to fit in the specified 
format, the printout will consist of a row of stars: 
ot 


TAB 


is a system function which is used in connection with 
the PRINT order. TAB is an abbreviation for 
TABul ation. 


Example: 


PRINT “Itemnumber: ",TAB(25) ,no After the text 
Itemnumber: has 
been printed, the 
system will move the 
cursor to column 25 
where no will be 
printed. 


See also PRINT FILE and SELECT OUTFUT. 

ZONE 
is a statement and a function which is used in 
connection with the comma (,)}. It 1s used to define 
the interval between columns in PRINT printouts. When 


COMAL is initiated and after the use of the command 
NEW, ZONE is equal to Oo. 


Examples: 
After start—up: 
PRINT 23,56,89 will be printed out as 


235689 with no spaces between numbers, 
because ZONE equals O. 


ZONE 5S The column interval is set to 5. 
PRINT 23,56,89 will now be printed out as 
23 eT =) 89 The first number will begin in 


column 1, the next in column 6, the 
next in ii, etc. 


spacing: ZONE ZONE can be used as function for 
example to assign a value to the 
variable spacing which is given 
the current ZONE value. 


PAGE ~- CURSOR 
PAGE 
can be used as a command or a statement. It is used to 


clear the screen. If a printer has been selected as 
the output device, a form feed order will be sent to 
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the printer. 
CURSOR 


can be used as a command or a statement. It can be 
used to position the cursor on the screen. The 
character position i,1 is in the upper left-hand 
corner, and 25,40 is in the lower right-hand corner. 


Examples: 

CURSOR 15,30 Place the cursor on line 15, 
column 30. 

CURSOR 0,10 Move the cursor to the present 


line, column 10. A O means 
present or current. 


Note that the specification of the screen position 
using CURSOR, INPUT AT and PRINT AT use the line and 
column method in contrast to high resolution graphics. 
In graphics the position is specified using a 
conventional (X,Y) coordinate system. 


READ -— DATA — RESTORE —- Labels - EOD 
READ 


is a statement which is used to read values from a DATA 
statement. If the READ statement contains several 
variable names, then these are separated by commas 

(,). 


Example: 
READ name$,street$,no,postno, towns 
DATA 


is a statement which contains the values which the 
variable names in a READ statement are assigned. DATA 
statements are not executed. For this reason they can 
be placed anywhere in a program. However DATA 
statements are local within a procedure or a function. 


Examples: 


The DATA statement can contain both text and numbers. 
Text must be enclosed within quotation marks “": 


DATA “John Smith", "Easton", "Pennsylvania" 


DATA 230, %0@6,411100110 a DATA statement can 
contain both decimal numbers, 
hexadecimal numbers and binary 
numbers. 
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RESTORE 


can be used as a command or as a statement. It sets 
the DATA pointer to point at the first DATA statement 
in a program or to the first statement right after a 
label. 


labels 


1s a freely chosen name which is used to specify an 
entry point at some line in the program. The label is 
not executed like an order. It can be used in 
connection with RESTORE (and GOTO). See the summary 
example after the definition of EQD. 


EOD 


is a boolean (logical) system function which is used 
during a READ from DATA statements. EQD means End 

Of Data. As long as DATA-values remain in the 

list, EQD is FALSE. When the last DATA-value has been 
read, then EOD is set to TRUE. 


Summary example: 


DATA "screws" ,112,"nails",50 
toys: 
DATA "“cars",220,"dolls",35 
DATA “balls",74,"jump ropes" ,24 
DIM names of 20 
RESTORE toys 
WHILE NOT EOD 
READ names,total 
PRINT "There are “stotalsname$; "left." 
ENDWHILE 


Notess 


It is usually convenient to place DATA statements near 
the beginning of the program, so they are easy to find 
and revise. 


€A label toys: has been placed just before the DATA 
statements containing the list of toys. 


RESTORE toys assures that READ begins in the 
following line. 


Read-in and printout of the toy inventory continues 
until EQD is set equal to TRUE. This happens when 
there is no DATA left in the list. 
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INSTRUCTIONS FOR COMMUNICATION WITH FILES 
MOUNT -— CREATE 
MOUNT 


can be used as a command or as a statement. It sets up 
a diskette which has just been placed in the disk 
drive, getting the diskette ready for reading and 
writing operations. Cassette tapes do not require 
this, and diskettes will usually operate properly 
without being MOUNTed. To be on the safe side it is 
wise to MOUNT diskettes each time they are put into the 


drive. 

Examples: 

MOUNT disk drive 9 is initialized. 

MOUNT "1i:" disk drive 1 is initialized. 
CREATE 


can be used as a command or as a statement. It creates 
a file on diskette. A file can also be created using 
the OPEN order, but communication with the file can be 
carried out about 10 times faster, when the file has 
been CREATEd first. 


Examples: 


CREATE “textfile",300,42 A file by the name of 
textfile with 300 
records, each 42 
characters (bytes) long. 


OPEN FILE/OPEN -— READ - WRITE — APPEND — RANDOM 
OPEN FILE/OPEN 


can be used as a command or as a statement. It is used 
to open access to a file on a peripheral device, e.q. 
diskette, cassette, printer etc. Several sequential 
files can be open at the same time with different 
stream numbers. The term stream number refers to that 
fact that a data channel is opened to or from the file. 
It the word FILE is omitted during program coding, the 
system will automatically add it to the listing after a 
SCAN or RUN. 


There are many ways to open files. See Chapter 6 for 
further information. In the following only a few 
examples of the use of READ, WRITE, APFEND and RANDOM 
will be given. 


Examples: 


OPEN FILE 3,"datafile" WRITE The file with the name 
datafile and stream 
number 3 is opened to 
receive data. 

Hereafter in the program 
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OPEN FILE 7,"“cs:names",READ 


OPEN FILE 15, "data" ,APPEND 


OPEN FILE 4,"names,usr" ,WRITE 


OPEN FILE 5,"text",RANDOM 42 


OPEN FILE 4,“lpslist" WRITE 


PRINT FILE — INPUT FILE 


PRINT FILE 
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stream number 3 is 
reserved for this file, 
until the file is closed 
by means of a CLOSE FILE 
3 order. 


The cassette file 
names is opened to 
return data to the 
Program. The file is 
identified by stream 
number 7. 


An already existing 
sequential disk file with 
the name data 1s opened 
for addition of new 

data following the 
existing data on the 
file. The file 1s 
identified by the stream 
number 15. | 


A sequential file 1s 
opened with the 
classification usr 
instead of seq. 


The file text is 

opened. RANDOM indicates 
that it is a random 
access file. Each 

record will have room for 
42 characters (1.e. 
bytes) on the diskette. 
42 bytes will be taken up 


on the diskette even 


though the individual 
records do not use all 
this room. Access to the 
records 1s speeded 
however, because each 
record has the same 
length. The position of 
each record can be 
determined when the 
record number is known. 


A file with the name 
list is opened to the 
printer. 


can be used as a command or as a statement. It 1s used 
for sending data in ASCII-format to a file on diskette, 
cassette tape or other peripheral. The file must have 
been previously opened by means of the OPEN order. The 
file is identified by its stream number. 


Chapter 4 - ~j]4- COMAL OVERVIEW 


When PRINT FILE is used to send data to a file, the 
individual data elements are separated by a carriage 
return <CR>, i.e. ASCII-code iS. 


A file which has been written to using PRINT FILE can 
be read using the order INPUT FILE. 


Examplesr 


PRINT FILE 2: items The value of the 
variable is written to 
the sequential file with 
stream number 2. The 
printout is terminated by 
a <CR> after items. 
The file is opened using 
OPEN 2,..,WRITE or 
APPEND. 


PRINT FILE 4,7: name$,town$s The values of the 
variables are written to 
the random access file 
with stream number 4, 
record number 7 (opened 
with RANDOM). 


INPUT FILE 


is a command or a statement used to read data from a 

file which has been opened with OPEN no,name?#,READ or 
RANDOM. The file must contain data in ASCII format, 

written with the PRINT FILE order. 


Examples: 


INPUT FILE 2: items The value of the 
variable is read in from 
the sequential file with 
stream number 2. The 
file must have been 
opened as a READ type. 


INPUT FILE 4,7: names, towns The values of the 
variables are read in 
from file 4, record 7. 
The file must have been 
opened as a RANDOM type. 


WRITE FILE — READ FILE 
WRITE FILE 


is a command or a statement which transfers data toa 
file in compact binary form. The file is sequential, 
if it 1s opened as a WRITE or APPEND type; and ‘it is 
random access, if it has been opened using RANDOM. 
WRITE FILE is preferable where possible instead of 
PRINT FILE, because the binary form takes up less 
space, and access is faster. It is not possible to use 
WRITE FILE to store data on a cassette tape unit. 
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Examples: 


WRITE FILE 2: first$,last$,tel 


WRITE FILE 3: tablevalues () 


WRITE FILE 4,12: no; text$; others 


READ FILE 
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The values of the 
variables are 
written in binary 
form to the 
sequential file with 
stream number 2. 
The file must have 
been opened earlier 
with the order OPEN 
2,..-- WRITE or 
APPEND. 


The entire set of 
numbers represented 
by tablevalues() 

is written to file 


“TY 
"os 


The values of the 
variables are 
written in binary 
form to a random 
access file. The 
stream number is 4, 
and the record 
number is 12. The 
tile must have been 
opened earlier using 
OPEN 4,...,RKANDOM. 


5S a command or a statement which 1s used to read data 
from a file which has previously been opened using the 


order OPEN no,name$,READ or RANDOM. 


The file must 


contain data in binary form, written with the order 


WRITE FILE. 
Examples: 


READ FILE 2: first$%,last$,tel 


READ FILE 4,12: nostexts; others 


The data values 

are read in from the 
sequential file with 
stream number Zz. 

The file must have 
been opened as a 
READ type. 


The data values 
are read in from 
file no 4, record 

1 re The file is 
random access and 
must have been 
opened with RANDOM. 
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CLOSE FILE/CLOSE 


can be used as a command or as a statement. It closes 
files which have been opened with the OPEN order. 
Serious errors can arise if one attempts to copy or 
rearrange open files. If the word FILE is omitted when 
this order is used as a statement, it will be added 
automatically by the system after a SCAN or RUN. 


Examples: 
CLOSE All open files are closed. 


CLOSE FILE 2 The file with stream number 2 
. is closed. 


UNIT - UNITS 
UNIT 


can be used as a command or as a statement. It is used 
to specify which unit is to be used for file operations 
when the file name does not contain this information. 
When COMAL is started, the disk drive number O is 
automatically selected as the unit. See Chapter 7 on 
Feripheral Equipment for further information. 


The following units may be selected: 


cee cassette 

Or disk drive no O (default) 

1s disk drive no 1 

2t extra disk drive (usual choice) 


Note that if a second disk drive is connected via the 
IEEE serial bus, it should be set up to act as ‘device 
i ae It will then repond to COMAL orders when 
referenced as unit 2. 


Example: 
UNIT “cos " Cassette is the default unit. 
UNITS 


is a system function which returns the name of the unit 
to be used, if no other specification is given in the 
file name. 


Example: 


PRINT UNITS the system responds e.g. with Or: 
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PROGRAMMING STRUCTURES 


Conditionals 

Loops 

Error Handling 
Procedures and functions 


CONDI TIONALS 


IF ~- THEN — ELIF —- ELSE - ENDIF 


are statements which are used in IF-THEN structures. 

An IF-THEN statement can be formulated in many 
different ways. The fundamental principle is, however, 
quite clear: If a <logical expression> is true, 

then the associated statements will be executed. 
Another way of expressing the same thing is to say that 
if a given <condition> is fulfilled, then the 
associated statements will be executed. 


Example 1s 

IF <logical expression> THEN <statement > 

is a single line version: If the <logical expression> 
is true, then the <statement> after THEN is executed. 


Otherwise the program just continues in the next line. 


IF answert="yes" THEN print ‘data 


Example 2s 
IF <logical expression> THEN Multiline version: 
<statement > If the expression is true, 
<statement > the statements between 
acanw THEN and ENDIF are 
ek executed. 
mee Otherwise execution jumps 
ENDIF to the line after ENDIF. 


IF number >=#0 THEN 

square ‘roots =SQR (number ) 

PRINT "The square root of "snumber;"is";square ‘root 
ENDIF 


Example Ss 

IF <logical expression> THEN 
bce If the expression is true, 
<statement > then the statements between 
ited THEN and ELSE are executed. 

Otherwise the statements 

ELSE ELSE and ENDIF are executed. 

<statement > 


ENDIF 
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IF answers IN “aeiou" THEN 
PRINT answers;"is a vowel." 
PRINT “Want to try again?" 
ELSE 
PRINT answers;"is not a vowel." 
PRINT "The letters: aeiou are vowels," 
PRINT “all other letters are usually consonants." 


ENDIF 

Example 4:3 

IF <conditioni> THEN ELIF is short for ELSE IF 
<statement> If <conditionl> is fulfilled, 
ace then the statements between 

ELIF <condition2> THEN and the first ELIF, 
<statement > are carried out. Then program 
ee execution continues after ENDIF. 
<statement > If <conditionl> is not fulfilled, 
sine then <condition2> is checked. If 

ENDIF true, then the statements down to 


the next ELIF are executed. 
Next, control passes to the 
line after ENDIF. Otherwise 
<condition3> is checked, etc. 


IF number=0 THEN 
add ‘data 

ELIF number®#1 
delete’data 

ELIF number®#2 


print ‘data 
ENDIF 
Example Sz 
IF <conditionl1> THEN If no condition 
<statement> is fulfilled, then the 
Pees statements between 
ELIF <condition2> ELSE and ENDIF are 
<statement > executed. 


ELSE © 
<statement > 


ENDIF 


IF a¢="mail" AND bs="box" THEN 
PRINT "Yes indeed!" 
PRINT "The word should be ;a%+b$ 
ELIF at="box" AND b$=#"mail" 
PRINT "Try reversing the words." 
ELSE 
PRINT “The words don’t agree." 
PRINT “Look at the drawing again," 
PRINT “and try again!” 
ENDIF 
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CASE - OF — WHEN - OTHERWISE — ENDCASE 


are statements which are used in the CASE-structure 
to direct program execution in a situation where a 
number of choices are available. 


Example: 


CASE <expression> OF 
WHEN <1. value> 
<statement> 

WHEN <2. value> 
<statement > 

WHEN <S. value> 
<statement > 


OTHERWISE (‘can be left out) 
<statement > 


ENDCASE 

CASE answer OF Depending on the value of 

WHEN 1 answer, one of the procedures 
PRINT "Hm..." will be executed. If the answer 

WHEN 2 is 1,2,3 or 4, then the statements 
tegn’linie under the corresponding WHEN are 

WHEN 3,4 executed. Otherwise the statements 
tegn ‘polygon following OTHERWISE are carried out. 

OTHERWISE The structure ends with ENDCASE. 
tegn ‘cirkel 

ENDCASE 


Special example: 


CASE TRUE OF 
WHEN denominator >0 
PRINT "Positive denominator" 
WHEN denominator=0 
PRINT "Be careful!" 
PRINT "Denominator is zero." 
WHEN denominator<oO 
PRINT "Negative denominator" 
PRINT "The sign is changed!" 
denominator : =—denominator 
ENDCASE 


LOOP STATEMENTS 


REPEAT - UNTIL 


are statements which are used in the REPEAT- 
structure. The statements within the REPEAT-UNTIL 
loop are repeated until the logical (boolean) 
expression in the UNTIL statement is true. 


Example 1: 
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REPEAT <statement> UNTIL <logical expression> 


is a single line version: 
<statement> is executed until <logical 
expression> is true. 


REPEAT read’file UNTIL text#=#"Susan" OR EOF (no) 


The procedure read’file will be 

carried out until the logical expression 
is true. Her is udtrykket, that the 
variable text is equal to "Jens", or 
EOF (nr) is true (which will occur if 
there is no more text in the file being 


read). @ 


Example 2: 

REPEAT Multi-line version: 
<statement > The statements between REPEAT 
aan and UNTIL run until the 


UNTIL <logical expression> logical expression is true. 


REPEAT The INPUT statement will be 
INPUT "New number ": a Carried out until 
UNTIL a<O the number read in is negative. 


Note that the statements in the REPEAT structure are 
always carried out at least once, because the logical 
expression is at the end of the loop. 


WHILE — DO — ENDWHILE 


are statements which are used in the WHILE-structure. 
The statements within the WHILE-ENDWHILE loop are 
repeated as long as the logical expression in the WHILE 
statement is true. 


Example 1: 

WHILE <logical expression> DO <statement> 
1s a single line version: @ 
As long as <logical expression? is true 
<statement> is executed. 

WHILE name$<>"Peter" DO get ‘name 
The call for the procedure get ‘name is 


repeated, as long as names is 
different from "Peter", 


Example 23 

WHILE <expression> DO As long as <expression> 
<statement> is true, the statements 
cee between DO and ENDWHILE 

ENDWHILE continue to be executed. 

bs=1 


WHILE KEY$=""0"" DO As long as no key is pressed, 
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bs: =24b new numbers in the series will 
PRINT 1/b continue to be printed out. 
ENDWHILE 


Notice that the keyword ENDWHILE must not be used in 
the single line version. 


FOR - TO — STEP - DO — ENDFOR 


are statements which are used in the FOR -— ENDFOR 
structure. The statements within the FOR loop are 
repeated a predetermined number of times, then program 
execution continues with the line after ENDFOR. The 
loop variable <counter> is local. 


Example 1: 
FOR <counter>:*<start?> TO <end> DO <statement> 


is a single line version: 

The loop is repeated <end>-<start>+1 
times with <counter> equal to 
<start>, <starto+1,..., until <end> 
is passed. 


FOR nzs#0 TO 3O DO PRINT a(n)3 
Example 2: 


FOR <counter *>s=<start> TO <end> DO 
<statement> 


ENDFOR <counter > 

FOR nor#1 TO 10 DO The FOR loop is repeated 10 
INPUT "Name: "“snames(no) times with the variable no 
INPUT “texts "stext$(no) equal to 1, 2,..., 10. 

ENDFOR no 

Example 33 

Version with STEP parameter: 


FOR angles:=0 TO 6.3 STEP 0.1 DO As indicated by 


PRINT COS (angle) sSIN (angle) the STEF parameter , 
PRINT COS(angle)“*2+SINCangle)*2 angle will take on 
ENDFOR angle the values: 

O, O.1,.2., 6.35 
FOR i#@s=max TO min STEP -1 DO The integer variable i¢ 
movetoa (0,0) increases the speed. 
Grawto (x (i#) ,y (i #) ) The STEP parameter can 
ENDFOR i# also be negative. 
Notes 


The keyword ENDFOR is not used in the single line 
version. 


The single line version can also be used as a command. 
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LOOP — EXIT - EXIT WHEN —- ENDLOOP 


are statements which are used in the LOOP-ENDLOOP 
structure. The statements in the LOOP-ENDLOOP segment 
are repeated until an EXIT or EXIT WHEN statement is 
executed. Next program execution is continued in the 
line after ENDLOOP. There can be O, 1 or more EXIT’s 
in a LOOP-ENDLOOP structure. 


Examples 


LOOP 
<statement > 


EXIT WHEN <logical expression> @ 
<statement > 


ENDLOOP 


LOOP 
INPUT "Text “: text$ Text is read in, written 
EXIT WHEN text$="end" to file 3 and examined in the 
WRITE FILE 3: text$ procedure do‘test, 
do ‘test until the text "end" 
ENDLOOP is read in. 


ERROR HANDLING 
TRAP_-— HANDLER —- ENDTRAP 


are statements which are used to control program 
execution after errors are encountered. If errors 
occur in the statements between TRAP and HANDLER 
(called the TRAP part), then the statements between 
HANDLER and ENDTRAP (the HANDLER part) are executed. 
Otherwise the program continues with the line after 
ENDTRAP. In this way one can avoid having the program 
stop e.g. due to a user data-entry error. 


TRAP If errors occur during read-in, 
INPUT "No. "s: no the system will jump down to the 

HANDLER HANDLER part and carry out the 
check ‘error procedure check’error. 

ENDTRAP 


ERR ~ ERRFILE —- ERRTEXTS 
are system functions which are used in connection with 
the HANDLER part of the TRAP structure to identify 
errors. See Appendix F on error numbers and error 
messages. 


ERR contains the error number. 


ERRFILE contains the number of a file, if one was in 
use when a read or write error occurs. 


ERRTEXT# contains the text with the error message. 
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Example i: 


TRAP 
INPUT "Exponent ":exponent 
PRINT 10“exponent 
HANDLER 
PRINT ERRTEXTS 
CASE ERR OF 
WHEN 2 
PRINT "Exponent too large" 
WHEN 206 
PRINT “Exponent is a number" 
OTHERWISE 
PRINT "Please try again!“ 
ENDCASE 
ENDTRAP 


Example 2: 


TRAP 
INPUT "Filename: "“:name$s 
OPEN 2,name$,READ 
OPEN 3, “savefile" ,WRITE 
transfer (names, “savefile") 
HANDLER 
CLOSE 
IF ERRFILE#=2 THEN 
PRINT “Error in read-in" 
ELIF ERRFILE=3 
PRINT “Error during print—out”" 


ELSE 
PRINT "Not an input/output error" 
ENDIF 
PRINT ERR,ERRTEXTS 
ENDTRAP 


REPORT 


1s a command and statement which is used in connection 
with the TRAP-structure. REPORT can be used in 
several ways to reveal an error and to direct 
subsequent error handling. REPORT can be used with or 
without an argument: 


REPORT Repeat earlier error. 
(only as statement) 


REPORT errorno Report an error with errorno. 
REPORT errorno,errortextsS Report errorno and errortext$. 


The order has various effects according to where it 
occurs in the structure. 


REPORT outside the TRAP-ENDTRAP structure: 
The error is reported to the system, which will then 
react to the error. 


REPORT in TRAP part of the structure: 
Program execution is directed to the HANDLER part, 
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where the user program handles the error. 


REPORT in HANDLER part of the structure: 

Program execution is directed to an external HANDLER 
structure, if found. Otherwise the error is reported 
to the system with an error message on the screen. 


Example: 
TRAP REPORT can sort out 
INPUT "Names: "“:names errors: 
INPUT “Ages "sage If the response to Age 
HANDLER is not a number, or the 
IF ERR#=2 OR ERR#®206 THEN number is too large, then 
age: =0 age is set equal to O. 
. LSE & 
REPORT Otherwise the error is 
ENDIF reported to the system. 
ENDTRAP 


GOTO -~— <Label:> 
GOTO 


is a statement which causes program execution to 
continue at a predetermined place. This place is given 
by a <Label>, i.e. a name followed by a colon (2). 

It is not possible to jump out of a procedure or intoa 
closed program structure using GOTO. 


Examples 


FOR nor#1 TO 10 DO 
READ FILE 2: number 
IF number<1e-37 THEN GOTO too’small 
PRINT 1/number 

ENDFOR no 

too ’smalls: 

PRINT "“Divisor too small." 


<Label:> @ 


is a name which is used to identify a program line. 
The program line is not executed. Execution continues 
in the line following <Labelr>. Labels are used in 
connection with GOTO and RESTORE. 


Examples: 


See GOTO example. 


DATA 2,4,5,2,1 Read-in of numbers from 
twodigits the DATA statements starts with 
DATA 12,34,18,54,22 the number 12 due to the 
RESTORE twodigit statement RESTORE twodigit. 


WHILE NOT EOD 
READ number (no), 
ENDWHILE 
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PROCEDURES 
PROC -— ENDPROC 


are statements which are used to form the PROC—-ENDPROC 
structure. PROC-ENDPROC surround a number of 
statements which together form a procedure. A 
procedure is a program module, recognized by a name 
stated in the procedure heading: PROC <name>. The 
procedure is carried out only if it is called from 
somewhere else in the program using the same name that 
appears in the PROC heading. 


COMAL programs should be created using procedures. In 
their simplest form, they can be used to break a larger 
Program down into smaller, easy to handle units. More 
advanced uses with parameter transfer and use of the 
options REF, CLOSED, IMPORT and EXTERNAL make 
procedures a programming tool of substantial value. 


Example 1: 


// MAIN PROGRAM 
<statement > 
<namei>d 
<statement > 
<name2> 
<statement > 
<namei>d 
<statement > 


END // MAIN PROGRAM 


PROC <namei> 
<statement = 


ENDPROC <namei> 


PROC <name2> 
<statement > 


ENDPROC <name2> 


The statements of the procedure are enclosed in PROC 
<name> and ENDPROC <name>. The procedure can be 
called “by name" from various places in the main 


program. 
// MAIN PROGRAM The main program consists of 
start ‘up program lines, each of which 


read ‘in calls a procedure. 





Chapter 4 - -126- COMAL OVERVIEW 


PROC start ‘up 
USE system 
textcolors(0,2,1) 
DIM number (10) 
PAGE 

ENDPROC start ‘up 


PROC read‘in 
FOR nos:#1 TO 10 DO 
PRINT “Read in age (",no,") ", 
INPUT ""s number (no): 
ENDFOR no 
ENDPROC read ‘in 


Example 2: e 


<statement > 
print ‘out (member , age,name$) 
<statement> 


PROC print ‘out (no, years, texts) 


PRINT 

PRINT “Membership numbers ",no 
PRINT "Age s ", years 
PRINT “Name s “,texts 


ENDPROC print ‘out 
Notes on example 2:3 


In the main program the procedure print’out is 

called. Those values which are contained in the actual 
parameters member, age and names, are transferred 

to the formal parameters no, years and text$, 

which occur in the procedure heading. 


The variable names of the formal parameters are local 
within the procedure print ‘out. 


This form for value transfer is one-way: Values can be @ 
passed into the procedure but not from it. 


Notes on procedures: 


When a procedure has been RUN or SCANned, it can be 
used as a command. 


A procedure can call another procedure, or it can even 
call itself. 


A procedure can be placed within another procedure and 
thereby be made local for just this procedure. 
(Similarly, a function and a label will be local within 
a procedure/function. ) 


The command SETEXEC will cause every procedure call 
in the listing to begin with the word EXEC (for 
"execute”). See SETEXEC. 
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REF -—- CLOSED - IMPORT 


is a parameter type which is used ina procedure call. 
A REF preceding a parameter in the procedure heading 
indicates that the name will only be synonomous with 
the corresponding name in the procedure call. It is 
called by reference. No room is reserved in the 
computer ’s working memory for a new name and value. 
The value receives only a new, temporary name. Both 
names refer to the same value. In this way room is 
saved in storage, execution speed is increased, and 
parameter values can be passed both ways: into and out 
of the procedure. 


Examples 


<statement > 
read’in(class ,name$()) 
<statement > 
PROC read’in(REF no,REF a$()) 
INPUT "Which class: ": no 
PRINT "Write student names. " 
is=0 
REPEAT 
is+1 
INPUT "Names "3s: a%(i) 
UNTIL a#@(i)=#"" 
ENDPROC read ‘in 


While the procedure read‘in is carried out, the names 
Class and no will refer to the same value because 

of the REF in front of no. The same is true for the 
names name$ and a$$. Hoth refer to the string 

values in a one-dimensional array. 


CLOSED 


is an order which is used to declare all variable names 
in a procedure as local. Thus the procedure is ‘closed 
off’ from the rest of the program except for transfer 
of parameter values in the parentheses of the procedure 
heading. In this way mixing and name conflicts between 
procedure names and variable names in the rest of the 
program can be avoided. For example a name can be used 
locally in the procedure without disturbing the value 
of a variable with the same name outside the procedure. 


Examples 


<statement > 

minmax (10 number () ,min,max ) 
PRINT ming max 

<statement > 
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PROC minmax (n,a() ,REF b,REF c) CLOSED 
bsma(1) 303 =al(2) 
FOR i#:=2 TO n DO 
IF a(i#)<b THEN bewa(i#) 
IF a(i#) 5c THEN cz:a(i#) 
ENDFOR i 
ENDPROC minmax 


The procedure minmax is CLOSED so that it can be used 
without worrying about the names of the variables in 
the procedure. 


IMPORT 


is a statement which is used in closed procedures to 
bring in variables, procedures and functions from 

outside the procedure. In this way they can be made 
accessible for use in an otherwise closed procedure. 


Example: 


<statement > 
print ‘out (points () ) 
<statement > 
PROC print ‘out (number ()) CLOSED 
IMPORT total, t(), sort 
DIM prod (total ) 
FOR no#:#1 TO total DO 
prod (no#) : =number (no#) #t (no#) 
PRINT nos proc (no#) 
ENDFOR no# 
sort (number () , total ) 
sort (t() ,total ) 
FOR no#:#1 TO total DO 
PRINT nots number (no#) #t (not) 
ENDFOR 
ENDPROC print ‘out 


Even though the procedure print ’out is closed, the 
variable total, the table t() and the procedure 
sort are made accessible by means of the IMPORT 
statement. 


EXTERNAL — MAIN 
EXTERNAL 


is a keyword which is used to indicate that a given 
procedure is an external procedure which must be 
fetched from the diskette when it is to be used in the 
program. When creating a procedure for use as an 
EXTERNAL procedure, it must be closed using the CLOSED 
order and saved using the command SAVE. The SAVEd 
procedure can be fetched from the diskette later for 
use in another program, provided it is declared to be 
EXTERNAL in this program. In this way it is possible 
to build up a library of procedures. The procedures 
can then be fetched into the working memory as need for 
use 1n programs. 
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Examples 


Let 


PROC test (a,b%,REF check) CLOSED 
IF a=O AND bs IN "abcd" THEN check: =TRUE 
ENDPROC test 


The procedure test is CLOSED and SAVEd on diskette 
with the command SAVE test "ext.test". 


It can be used later in another program. 


// Program start 

<statement > 

test (no, text$,error) 

<statement > 

PROC test (no,text$,REF error) EXTERNAL "ext. test“ 
// Program end 


This program will fetch the procedure test from 
diskette, use it and "forget" it again. 


The line with the EXTERNAL declaration can be placed 
anywhere in the program. 


MAIN 


1S a command which is used to bring the system back to 
the main program, if it should stop during the 
execution of an EXTERNAL procedure. If execution is 
stopped in an external procedure, LIST and other 
editing orders will work only on the external 
procedure, until MAIN removes it and brings back the 
main program. 


FUNCTIONS 
FUNC ~- ENDFUNC —- RETURN 


are statements which are used in the FUNC-ENDFUNC 
structure. This structure consists of a number of 
statements which together compose a user-defined 
function. Functions must be introduced with FUNC 
<name> and terminated by ENDFUNC <name>. The value 
which the function returns must be given ina 
RETURN-statement. 


Functions can be real functions, integer functions or 
string functions. A function is computed only if it 1s 
called somewhere in the program by the same name which 
is indicated in the function heading (FUNC <name>). 


Functions can be associated with the same properties 
which were available for procedures: REF, CLOSED, 
IMPORT and (<parameter list>). See also under these 
keywords in Chapter 4. In addition you will find that 
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functions are used in Chapter 3 and in Appendices C and 
E. 


In particular, all functions (after structure check 
caused by SCAN or RUN) can be called as direct 
commands. 


Example 1: 


// Main program 
// real function 
<statements> 
PRINT average (a,b) 
<statements> 


FUNC average (x,y) 
RETURN (x+y) /2 
ENDFUNC average 


Example 23 


// Main program 

// integer function 

<statements> 
first#: =vowel s# ("COMAL") 
second#: =vowels#("and functions") 
<statements> 


FUNC vowel s#(texts) CLOSED 
FOR i#:=#1 TO LEN(texts) DO 
IF textS(ié:i#) IN “aeiouAEIOU" THEN number#: +1 
ENDFOR i# 
RETURN number# 
ENDFUNC vowels 


Example 3: 


// Main program 

// setring function 
<statements> 

PRINT mystical$ ("secret") 
<statements> 


FUNC mystical $ (as) 
doublei= 2#LEN (as) 
DIM bs OF 1, cS OF double 
c$: =as 
FOR is=#1 TO LEN(as) STEP 2 DO 
bs CHRS (RND (65,93) ) 
c$e_ech (21) +bS+c$ (i+ ) 
ENDFOR i 
RETURN cS? 
ENDFUNC mystical$ 


Example 4: 


PRINT grabs(0,"Once upon a time") 
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FUNC grabs (first,as) 
lengths *LEN (as) 
IF length>1 THEN 
IF first THEN 
RETURN a$(2:) 
ELSE 
RETURN a$#(:length-1) 
ENDIF 
ELSE 
RETURN "" 
ENDIF 
ENDFUNC grabs 


OTHER FUNCTIONS 
@ ABS — INT - SGN —- SQR — PI 
ABS 
is a function which calculates the absolute value of an 
expression. It 1s sometimes called the numerical 
value. If the numerical value of the expression is 


negative, the sign is changed to positive. A positive 
value remains unchanged. 


Examples: 

ABS (3.25) equals 3.25 

ABS (~—7. 46) equals 7.46 

ABS (x—-7) the result depends on the value of x. 
INT 


is a function which calculates the integer part of the 
value of an expression, i.e. the largest integer (whole 
number) which is less than or equal to the value of the 
given expression. 


Examples: 
INT (3.235) equals 2 
@ INT (-7.46) equals -8 
INT (1/2) equals Oo 
SGN 


is a function which assumes the-value +1, O or -1, when 
the value of a given expression is positive, zero or 
negative respectively. 


Examples: 


SGN (327.54) equals +1 
SGN (-45. 7) equals -1 
SGN (0) equals 0O 
SGN (x /7~-y) the result depends on x and y. 
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SQR 


PI 


is a function which returns the square root. The 
argument must be non negative (i.e. positive or zero). 


Examplest 


SQR (14) equals 4 
SQR (4. 9et+09) equals 70000 
SOR (x*2+y*2) the result depends on x and y. 


is a system constant which is assigned the value 
3.14159266. PI is particularly useful in connection 
with the use of angles in radian measure, where PI 
radians corresponds to 180 degrees. 


COs - SIN — TAN —- ATN 


COs 


is a function which calculates the cosine of a number. 
This number must be expressed in radians. 


x degrees = »x*#PI/180 radians 
x radians = x*180/PI degrees 


Examples: 
COS (PI /2) equals oO 
COS (2.5) equals -0.8011423616 


COS (v#P1I/1680) the result depends on the value of v. 


SIN 


is a function which calculates the sine of a number. 
This number must be expressed in radians. See under 
cos. 


Examples: 

SIN(PI/6) equals oO.5 

SINCangle) the result depends on the value of angle. 
TAN 


is a function which calculates the tangent of a number. 
This number must be expressed in radians. See under 
Cos. 


Examples: 


TAN (—-P1I/4) equals -i 
TAN (1.8) equals -4.28626168 
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ATN 


is a function which calculates the arc-tangent 


(inverse tangent) of a number. The result is a number, 


expressed in radians. 


Examples: 
ATN(1) equals 0.785398163 (PI/4) 
ATN (-200) equals -1.56579637 
LOG -— EXP 
LOG) 


is a function which calculates the natural logarithm of 


a positive number. LOG represents logarithms to the 
base e@, where e@ is equal to 2.71828183. t0G is the 
inverse function of EXP. 


Exampless 
LOG (1) equals 0O 
LOG (10) equals 2.20258509 
LOG (-2) is not defined 
LOG (EXP (x) ) equals x 
EXP 
represents the exponential function. EXF(x) = e raised 


to the x’th power, where @ is the base of the natural 
logarithms. EXF is the inverse function to LOG. 


e = 2.71828183 to good approximation. 


Examples: 

EXP (1) equals 2.716281835 (= e) 

EXP (3) equals e cubed = 20. 0855269 
EXP (t-a#. 2) the result depends on t and a. 
EXP (LOG (x) ) equals x 


CHRS - STRS —- SPCS 


CHRS 


is a string function which equals the character which 
corresponds to the ASCII code of the argument. The 


opposite operation is performed with the function ORD. 


See Appendix A for Commodore ASCII codes. 


Examples: 
CHRS (65) equals the character a 
CHRS (147) equals the code for clear screen 


CHR# (<value>) the result depends on value 
CHRS (ORD ("B")) equals the character B 
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STR$ 


is a string function which converts a numerical 
expression to a string. The reverse operation is 
performed by the function VAL. 


Examples: 
STR (1.34) equals the string "1.34" 
STR (2-5) equals the string "-3" 


STR#(VAL("7")) equals the string "7" 


SPCS 


is a string function which returns the specified number 
of spaces ("blanks"). 


Examples: 


PRINT "“1",SPC#$(10) ,"2" 


text$:= "a"+SPC$ (8) +" jk" 


blanks$: =SPC$ (LEN (name$) ) 


10 spaces are printed 
between 1 and 2. 


text$ is set equal to 
"a jk" 


blanks is a string 


with the same number of 
spaces as there are 
letters in name$. 


ORD —- VAL —- LEN 
ORD 
is a function. The value of ORD is the ASCII value of 
det first charcter in the string argument. The 
"reverse" operation can be carried out by the function 


CHR. 


See Appendix A for Commodore ASCII codes. 


Examples: 

ORD ("“F") equals i198 

ORD ("doors") equals 68 

ORD (by$) the result depends on by# 


ORD (CHR$ (8) ) equals 8 


VAL 


is a function which transforms a legal string argument 
to its corresponding numerical value. To be legal the 
string must be composed of the digits 0O,..,9, the signs 
+—-, decimal point . or e used to specify 
exponential notation. The reverse operation is carried 
out with the function STR$S. 


Hexadecimal and binart notation is permitted. 
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Examples: 
VAL ("123") equals the number 122 
VAL ("2"4"3") equals the number 23 
VAL ("4ea12") equals the number 4e+12 
VAL ("abe") illegal 
VAL (STR (2) ) equals the number 2 
VAL ("Sfe") equals the number 254 
LEN 
is a function, whose value is the length of the string 
argument. 
Examples: 
LEN ("abcd") equals the number 4 
LEN (names) the result depends on namet 
‘LENC"") equals the number 0 


LEN("a ki") equals the number 5 
TRUE - FALSE 
TRUE 
is a System constant which always equals Il. 
FALSE 


is a system constant which always equals O. 


TIME 


—— 


is a command, statement and function used with the 
system’s built-in real-time clock. 


The clock measures time in jiffies. 


= 60 jiffies. 
1 day = 5184000 jiffies 
(The clock is reset to zero.) 


ee ee me ee cee ce cr ee ce ce cr cr ec cr es ee we oe ee 


TIME can be used to set the clock or to read the time 
since the previous zeroing. 


Examples: 
TIME O The clock is zeroed. 
TIME 3600 The clock is set to 3600 jiffies, 


i.e. 1 minute. 


secri@INT (TIME/60) gec is set equal to the number 
of seconds since the last zeroing. 
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RANDOMIZE - RND 
RANDOMIZE 


is a command and statement which is used to place the 
random number generator at an arbitrary point in the 
random number series. The random numbers are created 
with the function RND. 


Examples: 


RANDOMIZE The initial placement in the number 
series is determined by the time 
interval since the last TIME operation. . 
Since the number of jiffies (1/60 sec) © 
will generally be quite random, a really 
random sequence can be assured. 


RANDOMIZE 6 If RANDOMIZE is followed by a 
number, this number will indicate the 
starting position in the random sequence 
each time random numbers are generated. 
This will cause the same sequence to be 
generated when RND is used. 


RND 


is a function which selects a random real number from a 
random number sequence of evenly distributed ‘random’ 
numbers. 


RANDOMIZE is used to position the random number 
generator at an arbitrary position (based on the clock) 
in this series. 


Examples: 
number : =RND An arbitrary real number between 
O and 1 is chosen: O<=RND<1. 
nos =RND (-10, 30) A random number chosen among -10,-9, 


.. 729,30 is selected. e 


PRINT RND(min,max) A random integer between min 
and max (inclusive) is printed 
out. 


ESC - TRAP ESC 


are keywords which contral the action of the <STOP> 
key. 


ESC is a system function. Its value depends on 
whether the statement TRAP ESC+ or the statement 
TRAP ESC- has been executed: 


If TRAP ESC+ has been executed (it is the default 
condition), then pressing the <STOP> key will interrupt 
program execution. The ESC function has no meaning. 


If TRAP ESC- has been executed, then pressing <STOP> 
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will NOT interrupt the program. ESC will have the 


value FALSE, until <STOP> is pressed. Then it will 


remain TRUE until the value of ESC is read in the 
program. 


Sample sequences 


TRAP ESC- The <STOP> key will now not stop 
the program and ESC is assigned the 
value FALSE. 

<STOP> is pressed ESC is set equal to TRUE. 


dummy: =ESC ESC is reset to FALSE. 
TRAP ESC+ The <STOP> key regains its usual 
function. 


OPERATORS 


See Appendix C for a more detailed treatment of 
operators. 


DIV — MOD 


DIV 


is an operator which yields the value of the whole 
number part of the quotient after division. x DIV y 
is the same as INT(x/y). 


Examples: 

5S DIV 2 equals 2 

74 DIV 10 equals 7 

(x+3) DIV y the result depends on x and y. 


MOD 


is an operator which computes the remainder after 
division. »x MOD y is the same as x-INT(x/y) #y. 


Examples: 
5S MOD 2 equals i1 
74 MOD 10 equals 4 


8.25 MOD 2.1 equals 1.95 
(4-x) MOD z the result depends on x and z. 
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LOGICAL OPERATORS 
NOT —- AND — AND THEN — OR —- OR ELSE 
NOT 


is a logical operator which changes the truth value of 
an expression. 


Truth tables 


TRUE FALSE 
FALSE TRUE 


Examples: 

WHILE NOT EOQF(2) DO 
READ FILE 2: number 
PRINT number 3 

ENDWHILE 


The loop continues until there is no more data in the 
file with stream number 2. 


IF NOT ok THEN read ‘status (ok) 


The procedure read’status is executed until the 
variable ok becomes TRUE (<>50). 


AND 
is a logical operator which determines the truth value 
of a combined expression, a AND b. The combined 


expression is only TRUE, if both a and b are true. 


Truth tables 


FALSE FALSE 
Examples: 
722 AND 323 Qives the value FALSE 

WHILE expression! AND expression2 DO make ‘drawing 
If both expression! and expression2 are TRUE, then 


the procedure make‘drawing is executed. Otherwise it 
is not. 
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AND THEN 


OR 


OR 


is.a logical operator which is an extension of the 
operator AND: a AND THEN b. The same rules apply to 
AND THEN as for AND; but if the first expression a is 
false, the expression b is not computed, for it is 
certain that the entire expression will be FALSE. 


Examples 


aSi="test"sis=i 
lengths #LEN (as) 
WHILE i<#length AND THEN a#(i)<>"." DO is+i 


For i:=5 an error will occur in the logical expression 
aZ(id<>".", if this case is not eliminated by the 
first condition. 


is a logical operator which determines the truth value 
Of a combined expression, a OR b. The combined 
expression is true, if just one of the expressions a 
or b is TRUE. 


Truth tables 


a b ' a OR b 
TRUE TRUE TRUE 
TRUE FALSE TRUE 


FALSE FALSE FALSE 
Examples: 
7=2 OR 32d Gives the value TRUE. 
REPEAT The statements in the REPEAT-— 
<statement > loop are repeated until 
o- a8 no>4 or ans? is 
UNTIL no>4 OR ans IN "yy" ay oora Y. 
ELSE 


is a logical operator which is an extension of the 
operator OR: a OR ELSE b. The same rules apply for 
OR ELSE as for OR; but if the first expression a is 
true, then the expression b is not calculated, since 
the combined expression must be TRUE. 


Examples 

IF a@#=O0 OR ELSE 6b/a#t>100 THEN new ‘problem 

If a@ equals O, then the first logical expression is 
true. In this case an evaluation of the last 


expression (involving an illegal division) is 
superfluous. 
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IN 


is a operator which returns the position of a search 
string in a given text: string IN text. 


The value is the number in the text of the first 
character in the search string. If the search string 
is not found, then the value O is returned. 


IN can therefore be used for example to determine if 
a response is contained ina string containing 
acceptable answers. 
Examples: 
xs="oram" IN “programing” x gets the value 4. © 
PRINT “mel” IN "Comal program" 0 is printed. 
IF answers IN “nN" THEN STOP If answers consists 
of the letter n or 


N, the expression is 
TRUE, and the program 


stops. 
Special examples 
If the search string is empty, i.e. equal to "", then 
IN returns the text length + 1. 
length:="" IN “Comal for CBM" length = 14. 


BITAND - BITOR - BITXOR 
BITAND 


is a logical (boolean) operator which executes an AND 
on each bit in the binary representation of two 
numbers: a BITAND b. 


All numbers which are to be compared with the @ 
operators BITAND, BITOR or BITXOR must be integers 

in the interval O-65535, i.e. binary numbers 

between ZO000000000000000 and 41111111111111111. 


Ruless 

BITAND a ‘b OO O1 10 11 E.g. % 1 O Oo 

------------------- AND AND AND 
oo ! 00 00 00 OO % Ai 1 Oo 
O01! 0001 00 01 =) -—-------- 
10 ' OO 00 10 10 Lt ‘@) @) 
11 ! oo 01 10 Ii 
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Examples: 


40011 BITAND 40101 gives “O001 (decimal 1) 
17 BITAND 18 gives 16 
fe BITAND 53 Gives 4 


IF PEEK (userport) BITAND %1100 THEN register 
If the contents of memory address userport has the 


bit pattern %00001100, then the procedure register 
will be executed. 


BITOR 


is a logical (boolean) operator which executes an OR on 
each bit of the binary representation of two numbers: 
a BITOR b. 


Rules: 

BITOR a 'b OO O1 10 11 Esge 4. «1 e) 1 

SHS pee ear arenas OR OR OR 
00 ! 00 O01 10 11 1 O O 
OL! Of Of 212 21200 22 2 2 2 2 2 2 meee a---- 
1S ae 10 11 10 11 1 Oo 1 
Li. ¢ 11 11 11 11 

Examples: 


41010 BITOR 240110 Gives %1110 (decimal 14) 
23 BITOR $1b gives 31 


BITXOR 


is a logical (boolean) operator which executes an XOR 
(i.e. an "exclusive OR") on each bit in the binary 
representation of two numbers: a BITOR b. 


Rules: 

BITXOR a ‘b OO O01 10 11 E.g. Z~ 1 .) 1 

Sap SS ee XOR XOR XOR 
00 !' OO O01 10 11 1 Oo eo) 
O1 !' 010011 10  =-HeH----- 
10 ! 10 11 00 O1 0 oO 1 
11 §' 11 10 01 O00 

Examples! 


%0011 BITXOR %1010 gives %1001 (decimal 9) 
17 BITXOR 6 gives 25 


OTHER ORDERS 


“l 


is a statement which allows the inclusion of comments 
in a program. The comment statement is not executed, 
but is used in the program to clarify its function. 
Comments make it easier for other programmers (or 
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yourself) who examine the program later to understand 
how it works. 


The comment lines take up room in the working memory 
but do not increase a program’s execution time. 


Examples: 

// graphics window cleared 

aZi=b#(1)+bS(LEN(bS)) // at=bs‘s first and last character 
TRACE 


is a command which is used to trace active procedure or rd 
function calls. TRACE can be used to help find the 
cause of an error in a program. 


Examples 


A program might be stopped in a procedure in line 740 
due to an error: 


TRACE 


the program stopped in 

0740 a$:=character$(1:3) 

inside 

0700 PROC print ‘out (no,character$) 
which was called in 

0O3O print ‘out (2,"k") 


IM 
is a command and statement which is used to reserve 
room in working memory for arrays containing numbers 
or text. 


As a statement it will usually occur in the beginning 
of a program to dimension global indexed variables, but 
it.can also be used locally within a closed procedure. 


Arrays with numbers: @ 
DIM tabel (350) The array can contain real 

numbers with indices Il, 

Lie aeoUs 
DIM x (20) ,y (20) A DIM-statement can contain 


several arrays, separated by 
commas (,). 


DIM point (-—10320) Array with index -10,-9, 
oa gp Oyeus 20 

DIM space(10,40,40) Three dimensional array 

DIM price (01100,3: 10) Two-dimensional array with 


indices 0,..,100 and 5,..,10 
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Note: 
If the array specification in the DIM statement does 
not include a lower index limit, it is automatically 


set equal to 1. 


When created by a DIM statement, all array values are 
set equal to O. 


String arrays: 


DIM name# OF 30 Room is reserved for 30 
characters in the string 
name$. 

DIM item#(10) OF 20 Room for up to 10 


item$—names. Each name may 
contain up to 20 characters. 


DIM text$(0:10,2:35) OF 80 text is a two- 
dimensional array of words 
of maximum 80 characters. 


Notes 


The first time a string is assigned a value, room is 
reserved in memory for 40 characters, if not previously 
declared by a DIM statement. 


One dimensioned a string is set equal to the empty 
string, "". 


PEEK — POKE 
PEEK 


is a function which fetches the contents of a given 
storage address. The result is an integer between O 
and 255. A "map" with an overview of the use and 
avallability of Commodore 64 memory addresses can be 
seen in Chapter 8 on Machine Language. 


Examples: 


lines: =PEEK (214) The line number on which the 
cursor is currently located is 
fetched from memory location 214 
and the variable line is assigned 
this value. 


PRINT PEEK ($dd00) Prints the contents of the 
parallel port. 


POKE 


is a command and a statement which is used to place a 
number directly into a storage address: 
POKE address ,number . 


You must be careful when using POKE, since sending 
wrong numbers to random addresses can do strange things 
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SYS 


NULL 


STOP 


to your program. If worst comes to worst, it may be 
necessary to power-down and power-up again to continue 
programming! 


Exampless 

POKE 198,90 The counter of the keyboard 
buffer is zeroed. I.e. the 
buffer is emptied. 

POKE #dd0O3,411110000 The direction register of 


the parallel port has the 
hexadecimal address #$dd0O3. 
This address will contain the 
binary number 2411110000 which 
sets bit O-3 to inputs and 
bits 4-7 to outputs. 


is a command and statement which directs program 
execution to a machinge code subroutine starting at the 
address specified. 


Example: 


SYS 4000 execute the machine code routine 
starting at (decimal) address 4000. 


SYS 30000 The system carries out a COMAL 
start-up (this can also be done directly 
from Basic to start COMAL). 


is a command or statement which is used to do 

nothing! In fact it is quite useful when creating 
pauses and other situations, where it is desired that 
the program be delayed until some event (say pressing a 
key) causes execution to proceed. 


Examples: 
FOR pause:#1 TO 1000 DO NULL 


WHILE KEYS=CHR#(0O) DO NULL 


~- END 


STOP 


is a statement which is used to stop the execution of a 
program. 


STOP can be placed anywhere in a program, and there 
can be several STOP-statements in a program. After the 
program has been stopped, the values of any variables 
can be examined and/or changed. Using the command 

CON the program can be caused to continue at the line 
following the STOP statement. However no changes in 
program syntax may be made. 
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Examples: 


STOP The program stops with the 
message: STOP at xxxx 


STOP “printout finished” The program stops with the 
message: printout finished. 


END 


is a statement which completely terminates program 
execution and marks the conclusion of a program. END 
can be placed anywhere in a program. In contrast to 
STOP, the program can’t be continued with the CON 
command. | 


Examples: 


END The program is terminated with 
the message: END at xxxx 


END "All finished!" The program is terminated with 
the message: All finished! 
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Chapter 3S — 
COoOMmMAL. PACKAGES 
WHAT IS A PACKAGE? 


In vour COMAL cartridge there are 11 program packages with 
useful procedures. The packages are written in machine code 
for speed and compactness. They can help you to take full 
advantage of the many resources available in COMAL and the 
Commodore 64. 





A package and its built-in procedures and functions is made 
accessible with the command or statement: 


USE <package name> 
where package name is one of the 11 names which follow: 


When a package has been activated, its procedures and 
functions are called by name just as the ordinary COMAL 
procedures and functions which the user can create. All 
package procedures can be used as commands as well as pro- 
gram statements. More than one package can be activated at 
a time. 


Overview of packages: 


9. paddles a procedure for reading the paddle inputs 
10. joysticks a procedure for reading joystick inputs 
11. lightpen »s Procedures for control of a light pen 


1. english » English error messages 
2. dansk » Danish error messages 
3. graphics » procedures for X-Y graphics 
4. turtle » Procedures for turtle (Logo) graphics 
3. sprites » Procedures for handling sprites 
6. sound » Procedures for controling the SID sound chip 
7. system »s Procedures for altering system configuration 
8. font » procedures for defining new character sets 
9 
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THE ENGLISH PACKAGE 


USE english activates then package. When activated, all 
COMAL error messages will be in English. When COMAL is 
started up, the command USE english is executed 
automatically. This package contains no procedures. 


THE DANISH PACKAGE 


USE dansk activates the package. All COMAL error messages 
will then be issued in Danish. The package contains no 
procedures. 


GRAPHICS WITH COMAL © 


With the Commmodore 64 you can work with two different 
display screens: A text screen and a graphics screen. 


To work with these screen you can imagine that the computer 
has two internal ‘maps’ which show the current state of each 
of these graphics screens. Only one of these maps can be 
shown on the display screen at a time. 


Normally you will be 
looking at the text 
screen. It consists of 
zo lines, each with room 
for 40 characters. Fosi- 
tion 1,1 is in the upper 
left-hand corner, and 
position 25,40 is at the 
lower right on your dis-— 
play screen. Thus the 
text screen has a total 
of 25 x 40 = 1000 dif- 
ferent character loca— saneue aanpe 
tions. Im each position ae AH EERE Ee ane? 
a letter, number or 
graphics character can be 
placed. 





The graphics screen con- 
sists of 320x200 = 64000 
dots: 320 horizontally 
and 200 vertically. The 
points are identified in 
a coordinate system by 
means of a pair of num— 
bers (X,Y). The point 
(0,0) on the display is 
located in the lower 
left-hand corner, and the 
point with coordinates 
(319,199) is in the upper 
right-hand corner. Each 
of these dots is some- 
times referred to as a 
pixel (picture 

element). 
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The procedures and functions which are used to draw on the 
graphics screen are made accessible when you use the order: 


USE graphics or USE turtle. 


When using the high resolution graphics screen, two further 
options are available: 


graphicscreen (OQ) » high resolution graphics 
graphicscreen (1) >; multicolor graphics 


Both orders make the graphics screen visible on the display 
and the text screen is hidden from view but available for 
later use. The difference between the two types of graphics 
display has to do with the number of possible color 
combinations which can be displayed. See the more detailed 
discussion of the graphicscreen order for further 
information about this. 


Use high resolution if you want to make drawings with lots 
of detail using just one color besides the background color. 


If the use of several colors is more important than details, 
then the multicolor graphics option is the one to use. 


A program which draws a yellow border around the display 
screen might look like this: 


USE graphics 
graphicscreen (1) 
pencolor (7) 

drawto (319,090) 

drawto (319,199) 

drawto (0,199) 

drawto (0,0) 

WHILE KEY$=CHR#(0) DO NULL 


The last line of the program keeps the graphics screen 
visible until any key is pressed. When a key pressed, the 
condition KEY? = CHR#(0) will no longer be fulfilled, and 
the program will end. The computer then displays the text 
screen, hiding the graphics screen. 


After the order USE graphics has been executed, you can 
use the function keys <€1> and <€3> to choose which of 
the graphics screens you wish to view: 


<#1i> , displays the text screen 
<#5> , shows the graphics screen 


The function key <f3> can still be used to issue the 
command USE turtle, causing a split screen to be 
‘displayed: 


<#3> , split screen: graphics screen with 4 lines 
scrolling text at the top 


While using COMAL graphics you are not limited to the use of 
coordinates in the range from (0,0) to (319,199). You can 
superimpose your own coordinate system onto the graphics 
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screen by using the order window. All graphics orders 
except for the order viewport and the sprite orders will 
then be referred to your coordinate system. 


Program examples 


USE graphics 
graphicscreen (1) 

window (-2,2,-1,1) 

moveto (0,0) 

drawto (2,-1) 

WHILE KEY$=CHRS(O) DO NULL 





The order window(-2,2,-1,1) superimposes a 
coordinatesystem onto the display screen. The point (-2,-1) & 
is now at the lower left-hand side of the screen, and (2,1) 

is at the upper right-hand corner. 


When high resolution graphics is started up using the order 
USE graphics, the coordinate system selected corresponds 

to the order window(0,319,0,199), in accord with the 
standard screen coordinates. The order USE turtle 
performs an automatic window(-160,159,-100,99), so that 

the origin (0,0) is at the center af the display screen. 


If you want to write text on the graphics BEE EED: you can 
use the special writing order plottext. 


Example: 


USE graphics 

graphicscreen (1) 
plottext(0,100,"COMAL graphics") 
WHILE KEY$=CHRS$(O) DO NULL 


In Chapter 2 there are further examples of the use of 
Qraphics procedures. In addition you will find many 
examples of the use of graphics on the demonstration 
diskette (or cassette tape) which accompanied your COMAL 
cartridge. 


GRAPHICS OVERVIEW @ 


The packages graphics and turtle contain the following 
orders: 


Definition of working area: 
viewport —- window 


Choice of graphics screen 
graphicecreen 


Choice of graphics screen: 
textscreen —- fullscreen —- splitscreen 


Clearing of graphics screens: 
clearscreen - clear 
Color choice: 
textcolor - textbackground - textborder 
pencolor - background - border 
getcolor 


and color graphics states 
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(X,Y) graphics: 
plot 


drawto - moveto 
draw -~- move 
setxy 

circle - arc 
xcor - ycor 


Intelligent color fills 
fill — paint 


Relative graphics: 
showturtle - hideturtle 
turtlesize 
home 
setheading - heading 
penup — pendown 
left —- right 
forward - back 
arcl - arcr 


Text on the graphics screen: 
textstyle - plottext 


Information on graphics modes: 
ing 

Storage and printing of the graphics image: 
savescreen - loadscreen 
printscreen 


In addition it is possible to use the following procedure 
names when the turtle package is activated: 


bk = back 

bg = background 
cs = clearscreen 
#d = forward 

ht = hideturtle 
lt = left 

pc = pencolor 

pd = pendown 

pu = penup 

rt = right 

seth = setheading 
st = showturtle 
textbg = textbackground 
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IN DEPTH LOOK AT GRAPHICS ORDERS: 
viewport (<vxmin>,<vxmax >,<vymin>,<vymax >) 


is a procedure which limits the are of 
the display screen in which one can 
define a coordinate system and draw. 


The parameters <vxmin>, <vxmax>, <vymin> 
and <vymax> always refer to the physical 
display screen itself with (0,0) in the 
lower, left-hand corner and (319,199) in 
the upper, right-hand corner. Note that 
this procedure is independent of any 
other coordinate system which may have 
been chosen using the window 

procedure. 





Examples 


viewport (0,159,0,99) It is not possible to draw 
outside the lower left 
quadrant of the display 
screen. 


window (<wxmin>,<wxmax >,<wymin>,<wymax >) 


is a procedure which defines the coordinate system in 
the given viewport. The pixel in the lower, left-hand 
corner of the viewport is assigned the coordinates 
(Cwxmin?,<wymin?>). The pixel in the upper, right-hand 
corner is assigned the coordinates (<wxmax>,<wymax >). 
All subsequent graphics orders (except viewport and 

the sprite commands) will be refered to this coordinate 
system until a new one is defined. 


On start-up with USE graphics the viewport is the 
entire display screen and the coordinate system is 
defined by window(0,319,0,199) 


On start-up with USE turtle the viewport is the 

entire display screen and the coordinate system is 

defined by window (-160,159,-100,99). Thus the point @ 
(O,0O) 1s in the middle of the display screen. 


Examples 
window (-1000, 2000 ,-100, 200) 
graphicscreen (<mode>) 
is a procedure which makes the graphics screen appear 
on the display screen and makes the the text screen 


invisible. 


The graphics screen can be made accessible in two 
different modes: 


graphicscreen (0) » High resolution graphics 
graphicscreen (1) » multi-color graphics 
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The difference between the two modes lies in the manner 
in which color is handled. The pixels of the display 
screen are not independent when using color: 


In mode 0 (high-resolution graphics) the points of 

the display are associated in blocks of 64 pixels: (8 
on each side). Within each block there may only be two 
different colors, one of which is the background color. 
If one attempts to give a pixel in the block a third 
color, then the entire block will get this color. 


In mode 1 (multi-color graphics) resolution in the 
horizontal direction is not as good, for the pixels are 
associated in pairs. This means that each block 
consists of 4 x 8 pairs. Each of these pairs can be 
assigned a color. If one of the elements of the pair is 
assigned a color, the other dot will automatically 
acquire the same color. Within each block four 
different colors can be displayed at the same time. 

One of them is the background color. If one attempts 
to introduce a fifth color, the fourth color will also 
be given the new color. 


textscreen 


1S a procedure which makes the text screen appear on 
the display screen. The graphics screen is not visible 
but still available in computer memory. 


It can be necessary in a program to switch back and 
forth between the text screen and the graphics screen. 
This would be the case if the program contains INFUT 
statements and must also be used for drawing. This may 
appear to be inconvenient. Gn the other hand it 
assures that a drawing will not be disturbed by 
unwanted text. 


fullscreen 


is a procedure which causes the entire display screen 
to be filled by the graphics screen. The instruction 
would be used when working with turtle graphics to 
Switch from the split screen (splitscreen) to the 
full graphics screen. 


splitscreen 


is a procedure which shows the graphics screen and a 
scrolling copy of the text screen with four lines of 
text and the cursor at the top of the display. 


When used as a command, USE turtle does an automatic 
splitscreen, but not when it is used as a program 
statement. 


clearscreen 


is a procedure which deletes the entire graphics image 
no matter what the active (viewport) may be. To 
delete means to change all pixels to the background 
color. 
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clear 


is a procedure which only deletes the graphics image 
within the drawing viewport. 


Examples 
viewport (0, 100,0,100) Only the 101 x 101 pixels 
clear in the lower, left-hand 


corner of display screen 
are cleared. 


COLORS: In the following procedures with color 
specifications, the variable <color> must be an 
integer from -1 to 15. (Note: -1 means the 
background color.) See also Appendix B on colors 
and color codes. 


textcolor (<color>) 


is a procedure which defines the color of the 
characters on the text screen. 


Examples 
textcolor (0) Black text is selected. 
textbackground (<color >) 


is a procedure which defines the background color of 
the text screen. 


textborder (<color>) 


1s a procedure which defines the color of the text 
screen border. 


pencolor (<color >) 


is a procedure which defines the color of the pen. 


Examples: 

pencolor (7) Yellow is selected as the 
drawing color. 

pencolor (-1) The background color is the 


drawing color. 


background (<color >) 


is a procedure which defines the graphics screen 
background color. 


border (<color >) 


is a procedure which defines the graphics screen border 
color. 
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getcolor (<x>,<y>) 


is a function. Its value equals the color code of the 
Pixel at location (<x>,<y>). 


If (<x>,<y>) is outside the drawing area determined by 
the procedure viewport, then getcolor (<x>,<y>) 
returns the value -1. 


The function getcolor does not change the current pen 
position. 


Examples: 


PRINT getcolor (1,2) 
IF getcolor (0,0)<O THEN move ‘center 


plot (<x0>,<y0>) 


is a procedure which places a dot at pen position 
(<xO0>,<yO>). 


Example: 


plot (4.3,56) 


drawto (<x>,<y>) 


1s a procedure which draws a line from the current pen 
position to the point (<x>d,<y>), which becomes the 
new pen position. 


Examples: 


drawto (100,200) 
drawto (-20, 4000) 


moveto (<x>,<y>) 


is a procedure which moves the pen to the point 
(<x>,<y>). 


Example: 


moveto (200, -25) 


draw (<dx>,<dy>) 


is a procedure which draws a line from the current pen 
position (<x0O>,<yO0>) to the point with coordinates 
(<xO>+<dx>,<yO>+<dy>) and changes the pen position to 
the endpoint. 


Examples: 


draw(0,100) vertical line 101 units long 
draw (-1.5,0. 4) 
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move (<dx>,<dy>) 


is a procedure which moves the pen without drawing from 
its current position (<x0O>,<yO>) to the point with 
coordinates (<x0>4<dx>,<y0Oo+<dy>). 


Examples: 


move (-3,20) 
move (-2000 ,O) 


setxy (<x>,<y>) 


is a procedure which positions the pen at the point 
with coordinates (<x>,<y>). If the pen is down, this 
procedure draws a line just as drawto(<x>,<y>). If 
the pen is up, it 1s moved just as with 
moveto(<x>,<y>). 


circle (<x0>,<y0>,<r>) 


is a procedure which draws a circle with the center in 
(<xO>,<yO>) and radius <r>. 


Whether the circle appears circular or elliptical 
depends upon your choice of the drawing region on the 
screen, the coordinate system and the adjustment of the 
vertical linearity of the TV or monitor screen. If the 
coordinate system has been selected in the drawing area 
so that the condition 

<wxmax> — <wxmin> <vymax> — <vymin> 

<wymax> — <wymin> <vxmax> — <vxmin> 


is fulfilled, then the circle should appear to be 
perfectly round on the screen. If not, try adjusting 
the vertical linearity of the TV or monitor. 


Example 1: 


When USE graphics is called, it carries out the 
following procedures automaticallys 


viewport (0,319,0,199) 
window (0,319,0,199) 


The height/width ratio is equal to 1, and 
circle(160,100,99) 
will draw a round circle on the middle of the screen. 
Example 2: 
viewport (200,300,800, 180) 
window (-1,1,-1,1) 
circle (0,0,1) 


yields a round circle on the upper right-hand side of 
the screen. 
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arc (<x0>,<y0>,<r>,<a0>,<da>) 
1s a procedure which draws an arc with the center at 
(C<xO>,<yO>) and radius of curvature <r>. The starting 
angle is <aQ> degrees and the arc will subtend <da*> 
degrees. 


Exampless 


arc (100,100,530, 45,90) 
arc (-20,25,30,15,-60) 


xcor and ycor 


© are functions. They equal, respectively, the current x 
and y coordinates of the pen. 


Examples: 


PRINT xcors ycor 
plottext (xcor,ycor,"Figure 1") 


fill (<x>,<y>) 
is a procedure which uses pencolor to 111 a region of 
the screen with color. The region to be filled in must 
contain the point (<xs,<y?). It must be bordered by a 
line or area of a different color or by an edge of 
the viewport. 
fill does not alter the pen position. 
See the summary example under the procedure paint (<x>,<y>). 
Example: 
#i111(¢10,56) 

paint (<x>,<y>) 

@ 1S a procedure which filis in a region of the screen 
with the drawing color. The region which 1s to be 
filled in must contain the point (<x ?,%ty>), and it must 
be bordered by a line or area with the same color or 
by an edge of the drawing area. 
paint does not alter the current pen position. 
Examples: 


paint (-10,4) 


pencolor (-1) 
paint (100,20) A region is ‘erased’. 


The collection of examples below illustrates the 
differences between fill and paint: 
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USE graphics 
graphicscreen (1) 
pencolor (7) 


drawto (319,199) 

#111¢10,100) // if paint (10,100), no difference 
pencolor (1) 

circle(100,100,70) 

#111 (100,100) // if paint (100,100), a difference! 


WHILE KEYS=*CHRS(0O) DO NULL 
showturtle 


is a procedure which causes the turtle to be displayed 
on the graphics screen. The word ‘turtle’ is based on 


the use of relative graphics in the computer language @ 
Logo. P 
USE turtle automatically causes the turtle to be 
shown. 

hideturtle 


is a procedure which causes the turtle on the graphics 
screen to become invisible. 


turtlesize (<size>) 


is a procedure which defines size of the drawing 
arrowhead (the turtle). 


The parameter <size> must be a number between O and 10. 
When graphics is started up, this parameter is 
automatically set equal to 10. 


home 


is a procedure which places the turtle at coordinates 
(0,0) pointed upwards on the screen. 


setheading (<heading>) 


1s a procedure which sets the direction in which the r 
turtle points. If the turtle is visible, it will turn 
to face this direction. 


<heading> is given in degrees: 

O corresponds to upwards. 

90 is towards the right side of the screen. 
-90 is towards the left. 


USE turtle automatically sets the heading to O. 

heading 
is a function which returns the value of den current 
heading. The heading is given in degrees with O towards 


the top of the screen, and 90 degrees towards the 
right. 
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is a procedure which lifts the pen. 


pendown 


is a procedure which lowers the pen. It causes the 


turtle to draw as it moves. 


When graphics is started up, the system automatically 


executes a pendown. 


left (<angle>) 


is a procedure which turns the turtle <angle> degrees 


to the left in relation to the 


right (<angle>) 


current heading. 


is a procedure which turns the turtle <angle> degrees 
to the right in relation to the current heading. 


forward (<distance>) 


1s a procedure which moves the 
units forward with the current 
down, a line is drawn. 


back (<distance>) 
is a procedure which moves the 
units backwards in relation to 
The turtle "backs up." If the 


drawn. 


Summary example: 


turtle <distance> 
heading. If the pen is 


turtle <distance> 
the current heading. 
pen is down, a line is 


Press the <€3> function key (corresponding to the 
USE turtle command). Write directly on the four text 


lines which are visible at the 


left (90) 
forward (70) 
right (130) 
forward (80) 
left (40) 
back (100) 
hideturtle 


top of the screen: 


The turtle has now drawn a number 4. 


arcl (<r>,<da>) 


is a procedure which draws a left-hand arc with a 
radius of curvature <r> and subtending an angle of 
<da> degrees. The starting point is the current 
turtle position, and the starting direction is the 


current heading. 
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Examples: 
forward (20) After having drawn a straight line, 
arcl(50,30)  $=‘The line curves towards the 


left, turning 30 degrees. 
Procedure example: 


PROC soft ‘frame (xmin,ymin,width,height) 
IF width>20 AND height>20 THEN 
width=width-20 
hei ght=height-20 
moveto (xmin+10, ymin) 
setheading (90) 
forward (width) 
arcl (10,90) 
forward (height) 
arci (10,90) 
forward (width) 
arcl (10,90) 
forward (height) 
arcl] (10,90) 
ENDIF 
ENDPROC -soft ’frame 


arcr (<r>,<da>) 


is a procedure which draws a curve to the right with 
radius of curvature <r> and turning angle <da>. 

The starting point is the current position of the pen, 
and the initial heading is the current heading. 


arcr (<r>,<da>) corresponds to arcl (~<r>,-<da>). 
Examples 
arcr (3.45,50) 

wrap 


is a procedure which allows lines 

drawn on the graphics screen to 

continue beyond the edge of the 

screen, reappearing on the opposite 

side. For example, if the pen 

disappears at the top of the screen 

with x-coordinate 110 and heading Vi 
45, it will reappear at the bottom 

with the same x-coordinate and the 

same heading. 


When USE turtle is engaged, the procedure wrap is 
carried out automatically. This is however NOT the 
case when USE graphics is started. 


nowr ap 


is a procedure which terminates ‘wraparound’. It can 
be restored with the procedure wrap. 
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textstyle (<width>,<height>,<heading>,<mode>) 


is a procedure which is used to define how text 
printout will appear on the graphics screen. The 
actual printing of text is performed with the procedure 
plottext. 


The parameters <width?>, <height>, <heading> and <mode> 
must all be integers. 


<width> = letter width (1 corresponds to normal text.) 
<height> = letter height (1 corresponds to normal text.) 
<heading> = O , text is rotated O degrees. 

1 , text is rotated 90 degrees. 

2 , text is rotated 180 degrees. 

> , text is rotated 270 degrees. 
<mode > = OQ , both the text and its background color is 


drawn. This means that the text area is 
cleared before new text is printed. 


1 , only the characters of the text are printed. 
This means that a letter a placed on top of a 
letter b will not delete the entire letter 
b. Some of the remnants of the b will 
still be visible. 


If a parameter is set equal to -1, then the current value is 
used. 


On startup the computer automatically chooses 
textstyle(1,1,0,0), corresponding to normal text size ias on 
the text screen) written horizontally, and both text and its 
background color is printed. 


Example: 

textstyle(2,1,2,0) All subsequent text will be written 
upside down with characters of double 
width. 

textstyle(3,2,-1,-1) Only the text size is changed. 


plottext (<x>,<y>,<text$>) 


is a procedure which prints out the given text starting at the 
point (kx>,<y>). 


The size of the letters, the orientation and writing mode are 
specified by the procedure textstyle. 


plottext does not change the position of the pen. 
Examples: 

plottext (100,150, "COMAL") 

text$:="What‘'s my name?” 


textstyle(1,5,1,0) 
plottext (200,10,text$) 
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is a function which is used to obtain information concerning th 
state of the various graphics variables. 


The parameter <no> must be an integer between O and 33. 


<no> Information 

O display 

1 text border 

2 text backgnd. 
3 text color _ 
4 graf. border 

3 graf. backgnd. 
6& pen color 

7 gr.text width 
8 gr.text height 
9 gr.text dirn. 
10 gr.text state 
11 turtle visible 
12 inside window 
1S 6 txt scrm seen 
14 spilt scrn seen 
15 wraparound 

16 pen down 

17 »%* - position 
18 y - position 
19 ~vxmin 
2O vxmax 
z= vymin 
22 vymax 
25 wxmin 
24 wxmax 
av wymin 
= wymax 
27 COS(‘heading) 


28 SIN(heading) 


29 turtle size 
3O x-aspect ratio 
51 y-aspect ratio 


S2 x-text end 
y-text end 


savescr een (<filenames>) 


state 


COoOrRr TO COOCO 
| 


or i 


1S 
15 
15 
15 
15 
1S 
254 
2O4 


3 


or 1 


TRUE , FALSE 
TRUE , FALSE 
TRUE , FALSE 
TRUE , FALSE 
TRUE , FALSE 
TRUE , FALSE 
integer 
integer 
integer 
integer 
integer 
integer 


real 
real 
real 
real 


SLO) = 
-1.0 - 


0.0 
real 
real 


number 
number 
number 
number 
1.0 
1.0 
- 10.0 
number 
number 


integer 
integer 


affected by 


graphicscreen 

setcolors, border 
setcolors, textbackground 
setcolors, textcolor 
border 

background @ 
pencolor 

textstyle 

textstyle 

textstyle 

textstyle 

showturtle, hideturtle 
most drawing procedures 
screen 

screen 

wrap, nowrap 

penup, pendown 

most drawing procedures 
most drawing procedures 
viewport 

viewport 

viewport 

viewport 

window 

window 

window 

window 

seth, left,right ,home,arcl ,arcr 
seth, left,right,home,arcl ,arcr 
turtlesize 

= (wx max-wxmin) / (vxmax-vxmin) 
=(wymax—wymin) / (vymax-vymin) 
pilottext 

plottext 


1S a procedure which saves a copy of the current 


graphics screen on diskette or tape. 


under the name <filenames>. 


The contents of the file are: 


High resolution image (take up 36 blocks 


oO 
background color 
border color 


1000 bytes for colors O and 1 
8000 bytes for the bit pattern 


The file iss saved 


of 256 bytes): 
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Multi-color image (takes up 40 blocks of 256 bytes): 
1 
background color 
border color 
1000 bytes for colors 1 and 2 
1000 bytes for color 3 
8000 bytes for the bitpattern 


Examples: 
savescreen("grO.drawing") saves a high res image. 


savescreen("gri.circles") saves a multi-color image. 


loadscr een (<filenames$>) 


1S a procedure which fetches an image which previously 
had been saved on diskette or on tape. See 
savescreen. 

Examples: 


loadscreen ("gr0. drawing") 


loadscreen("gril.circles") 


printscreen (<filename$>,<position>) 


is a procedure which saves the contents of the current 
viewport to the file named <filename#>. 


The parameter <position? is an integer from O to 479. 
It specifies the horizontal placement of the image on 
the MPSSO1 printer. Six <position> units correspond to 
one character from the edge of the paper. 


The procedure is intended for getting a hard copy of a 
graphics image on the printer. But it can also be 
used, among other things, for saving a picture on 
diskette or on tape for later use. 


Note that hard copy to a printer can only be done if 
the printer is compatible with the Commodore MFS 801. 


High resolution graphics: 


Printing Color 
intensity 
O74 background color 


4/4 all other colors 
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Multi-color graphics: 


Colors are printed according to a grey scale: 


Printing Color 
intensity 
0/4 1: white 
1/4 3: cyan, 7: yellow, 13: light green, 
15: light grey 
2/4 4: purple, 5S: green, 8: orange, 
10: pink, 12: grey, 14: light blue 
3/4 2: red, 6: blue, 9: brown, 11: dark grey 
4/4 O: black 
Examples: 
printscreen("lp:",79) The graphics screen is 
: dumped to a MPS 801 printer. 
The image begins right after 
the 13th character position. 
printscreen ("head",19) The contents of the graphics 


screen are saved on diskette 
under the name head. 


The file can not be fetched again using the procedure 
loadscreen, but must be entered instead as an 

ordinary sequential file. The following program 
segment fetches the saved file and prints it out on the 
printer: 


OPEN FILE 2,"head",READ 

SELECT OUTPUT "“lp:" 

WHILE NOT EOF (2) PRINT GET#(2,5000) 
CLOSE FILE 2 

SELECT OUTPUT "ds:" 
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SPRITES 


With your Commodore 64 it is possible to define a small 
graphics image which can be moved about on the graphics 
screen. Such an image is called a sprite. 


Up to 8 sprites can be on the screen at one time. This 
makes it possible to create vivid graphics images with 
moving figures. For each sprite can be assigned its own 
color and be moved around independently of the others and 
the rest of the program. It is also possible to allow the 
sprites to interact with one another. 





A number of procedures and functions are available for 
controling sprites using the COMAL package sprites. 


The package is made accessible by issuing the order: 
USE sprites 


You can imagine that you are working with sprites as 
follows: 


You have a stage (the display screen) 

with a backdrop. (the graphics background) 
On the screen there are actors (sprites) 

which can move around (using movesprite) 

while performing an actiagn. (using animate) 


The actors can move on and off 

the stage. The actors can move 

in front of and behind one an- 

other, and they can move in 

front of and behind the props (graphics drawings) 
You can direct the actors 

using sprite commands. 
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Let ’s begin by making a sprite and moving it around the 
screen. This brief program shows how it can be done (it is 
called Sprite 1 on the demo diskette/tape): 


0100 DATA 400000000 , 400000000 , 400000000 
0110 DATA %00000000 , %00000000 , 00000000 
0120 DATA 400000000 , 400000000 , 400000000 
0130 DATA %400001110,400001110,Z00000000 
0140 DATA 400001111 ,%00011110,Z00000000 
0150 DATA 400000111 ,400111100, Z00000000 
01460 DATA 400000011 , 400110000 , 400000000 
0170 DATA 400000001 , 411100000 , 400000000 
0180 DATA 400000011 , 411100000 , 700000000 
0190 DATA 400000111 ,411110000, Z00000000 
0200 DATA 400000011 ,%411100000 , 400000000 
0210 DATA 400110001 ,%11000000 , 400000000 
0220 DATA 400111111,%11100000 , 400000000 
0230 DATA %00001111,%411110000, Z00000000 
0235 DATA %00000111,%11110000, Z00000000 
0240 DATA 400000111 ,%11100000 , %00000000 
0250 DATA %~00000111,%11100000, ~Z00000000 
0260 DATA 2400011111,411111000, ZO0000000 
0270 DATA %00111110,2401111100, 00000000 
0280 DATA 200000000 , 400000000 , 400000000 
0300 DATA %00000000 , 400000000 , 400000000 
0310 

O320 USE graphics 

O330 graphicscreen (0) 

0340 USE sprites 

O350 DIM drawings OF 64 

0360 FOR is:=1 TO 463 DO 

0370 READ byte 

O380 drawings: +CHR$ (byte) 

0390 ENDFOR i 

0400 color:#1 

0410 drawingno:=1 

0420 spritenos: #1 

0430 define (drawingno,drawings+""0"") 
0440 identify (spriteno,drawingno) 

0450 spritecolor (spriteno,color) 

0460 spritepos (spriteno,50,100) 

0470 showsprite(spriteno) 

0480 

0490 WHILE KEYS=@CHRS$(0) DO NULL 

0500 

03510 movesprite(spriteno, 250, 150,200,0) 
0520 

O3530 WHILE KEYS#CHR#(0) DO NULL 


The DATA statements in Lines 100-300 contain the definition 
of the figure. 


These numbers (which can be written directly in binary in 
COMAL simply by prefixing binary numbers with the % sign) 
are read in ASCII format in the FOR-ENDFOR loop (360-390). 
The text string drawings contains the bit pattern infor- 
mation which will form the sprite. 


In line 430 this drawing is given the number 1. The extra 
""O"" is included to specify that the drawing is a re- 
presentation in high resolution graphics (as opposed to 
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multi-color graphics). 


In line 440 sprite 1 is identified to correspond to drawing 
no 1. In line 450 the color of the sprite with number 1 is 
specified (color:=1, i.e. white). 


In line 460 sprite no 1 is placed on the screen so that the 
upper left hand corner of the figure is at (x,y) coordinates 
(50,100). Line 470 makes the sprite appear on the screen. 


When you have had enough of the rabbit, press any key. 


Line 510 causes the sprite to move over to the point with 
coordinates (250,150). The move is made in 200 steps. We 
will get back to the last O in the movesprite procedure 
call later. 


When you again press any key, the program ends. 


That was your first program using sprites. Now try giving 
the rabbit another color. Try moving it around to other 
points on the screen. 


THE SPRITE IS ENLARGED 
Try adding the program line: 
465 spritesize (spriteno, TRUE, TRUE) 


Run the program again. The sprite has become twice as high 
and twice as wide! 


MORE SPRITES 
Add the program lines 


472 identify (2,drawingno) 
474 spritecolor (2,0) 

476 spritepos (2,800,100) 
478 showsprite (2) 


Try out the program. Can you make the new sprite move? See 
if you can make the two sprites start at either side of the 
screen. Make them move towards one another so that they 
exchange places. 


You probably noticed that sprite no 1 passed in front of 
sprite no 2. The sprite with the lowest spriteno will 

always have first priority, so that the sprite with the 
lowest number will appear to pass in front of the other. 


TWO SPRITES COLLIDE 


The last number in the movesprite call determines how the 
sprite will move in relation to the other sprites and other 
graphics drawings on the screen. In the examples we have 
seen so far, it has been equal to O. 
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If the number is changed to 1 i line 510, the sprite will be 
instructed to detect a collision with the cther sprite. 
Both sprites will stop. Try it! 


SAVING A DRAWING ON DISKETTE 
You can save a drawing using the order 
saveshape (<drawingno>,<filenames>) 


Drawings can be saved either on diskette or on cassette 
tape. (NB: Use cas in the file name to save on tape.) 

The drawing can be fetched for use in another program with 
the order 


loadshape (<drawingno>,<filename$>) 


This can obviate the need for including all the DATA 
statements in programs using the same sprite image. 


The following program (Sprite 2) defines the drawing of 

the rabbit and saves this drawing on diskette under the name 
epO.rabbit. If you run this program, you will e.g. be 

able to replace lines 100-210, 2360-400 and 430 in other 
programs using the drawing with a single line: 


430 loadshape (drawingno, "spO.rabbit") 
First the drawing must be saved using: 


O100 til 0300: DATA statements with sprite image 
content (See previous program.) 

0310 

0320 USE sprites 

O330 DIM drawings OF 64 

0340 FOR is:#1 TO 63 DO 

O350 READ byte 

0360 drawings: +CHRS$ (byte) 

O370 ENDFOR i 

O380 drawingno: 1 

0390 define (drawingno,drawing$+""0"") 

0400 saveshape (drawingno, "spO.rabbit") 


SPRITES USED WITH OTHER GRAPHICS 


The following program shows how a sprite can be prepared to 
detect a collision with a graphics drawing and wait for the 
collision to happen. After the collision, the sprite can 
continue ina different direction. 
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0100 til O300: DATA statements with sprite image 
content (See previous program. ) 

0310 

0320 USE graphics 

O330 graphicscreen (0) 

0340 USE sprites 

O350 color:s=1 

O360 DIM drawings OF 64 

O370 FOR is=1 TO 63 DO 

0380 READ byte 

0390 drawing$: +CHR$ (byte) 

0400 ENDFOR i 

0410 drawingno: #1 

0420 spriteno:#2 

0430 define (drawingno,drawings+""0"") 

0440 identify (spriteno,drawingno) 

0450 spritecolor (spriteno,color) 

0460 spritepos (spriteno,50, 100) 

0470 showsprite(spriteno) 

0480 

0490 WHILE KEY$S=CHR$(0) DO NULL 

03500 

0510 make ‘box 

O520 movesprite (spriteno, 250, 150,200,4) 

O530 WHILE NOT datacollision(spriteno, TRUE) DO NULL 

03540 priority (spriteno, TRUE) 

OS550 movesprite(spriteno,130,180,50,0) 

03560 

0570 WHILE KEY$2CHRS$(0) DO NULL 

0380 

0590 PROC make ‘box 

0600 pencolor (8) 

0610 moveto(100,10)3; draw(30,0) 

0620 draw(0O,150)5; draw(-50,0)3 draw(0,-150) 

0630 #111¢105,13) 

0640 ENDPROC make’ box 


In line 520 the last number in the movesprite call is a 4. 
This causes the sprite to recognize collisions with graphics 
drawings. If 4 is changed QO, the rabbit will move past the 
box without noticing it. 


In line S30 there is a delay until a sprite-graphics 
collision occurs 


In line 540 it is determined that the sprite will be seen 
behind the graphics ddrawing. Try changing TRUE to FALSE 
and re-run the program. 


SPRITE CARTOONS 


By switching two or more drawings quickly in succession, one 
can cause the rabbit to appear ta perform actions while it 
moves. 


We begin by making a few small changes in the drawing of the 
rabbit which we already have used. (This is easiest to do 
by listing the DATA statements and changing them directly.) 


Next the order of the actions must be specified. This is 
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done by means of the order animate(<spriteno>,<action$>). 
The completed program (Sprite 4) might appear as follows: 


0100 DATA 400000000 , Z00000000 , 00000000 
0110 DATA 400000000 , Z00000000 , 400000000 
0120 DATA %00000000 , 400000000 , 400000000 
0130 DATA 400001110, 200000000 , 200000000 
0140 DATA %00001111,%00011110, ZO0000000 
0150 DATA %400000111,%00111111, XO0000000 
0160 DATA 400000011 , 400110111 , ZOO000000 
0170 DATA %00000001 ,%11100000 , 00000000 
0180 DATA 400000011 ,%11100000 , Z00000000 
0190 DATA 400000111 ,%11110000, 400000000 
0200 DATA 400000011 ,%11100000 , Z00000000 
0210 DATA 400000001 , 411000000 , 00000000 
0220 DATA 400000011 ,%11100000 , 400000000 
0230 DATA ~00111111,%11110000, 00000000 
0240 DATA 400111111,411110000, ZO0000000 
0250 DATA %00000111,%11100000 , ZO0000000 
0260 DATA 400000111 ,%11100000, Z00000000 
0270 DATA 400011111,411111000, ZO0000000 
0280 DATA 200111110,%401111100, ZO0000000 
0290 DATA %~00000000 , 400000000 , 400000000 
0300 DATA %00000000 , %~00000000 , Z00000000 


0320 DATA 400000000 , ~Z00000000 , 700000000 
O330 DATA Z~00000000 , 400000000 , 700000000 
0340 DATA %00000000 , %00000000 , 400000000 
0350 DATA %400001110,%00001110, Z00000000 
0360 DATA 700001111 ,%00011110,Z00000000 
0370 DATA 400000111 ,400111100, ZO0000000 
0380 DATA %0000001 1 ,%00110000 , 400000000 
0390 DATA %00000001 , 211100000, Z00000000 
0400 DATA 400000011 ,2%11100000, 400000000 
0410 DATA %00000111,%411110000, Z00000000 
0420 DATA 400000011 ,%11100000 , 400000000 
0430 DATA 400110001 ,411000000 , Z00000000 
0440 DATA 400111111,%11100000, 00000000 
0450 DATA 400001111,%11110000, ZO0000000 
0460 DATA 400000111,%11110000, 00000000 
0470 DATA 400000111 ,%11100000 , ZO0000000 
0480 DATA 400000111 ,%11100000 , 400000000 
0490 DATA 400011111,4%11111000, Z00000000 
0500 DATA 2400111110,401111100, ZO0000000 
0510 DATA Z£00000000 , 700000000 , 400000000 
0520 DATA %00000000 , 400000000 , 400000000 


0340 USE graphics 
0350 graphicscreen (1) 
03560 USE sprites 
03570 color:#1 





Chapter 5 - -j/l- COMAL PACKAGES 


03580 spriteno:=1 

03590 DIM drawingt OF 64, actions OF 64 
0600 FOR drawingnos#1 TO 2 DO 

0610 drawing$:=s"" 

0620 FOR is=1 TO 63 DO 

0630 READ byte 

0640 drawings: +CHRS (byte) 

0650 ENDFOR i 

0660 define (drawingno,drawings+""0"") 
0670 ENDFOR drawingno 

0680 

0690 identify (spriteno, 1) 

0700 spritecolor (spriteno,color? 

0710 spritepos (spriteno,50,100) 

0720 showsprite(spriteno) 

0730 actions: om ft a 1 ee i aa “wan ey oe won ot yg at pois fs a6 
0740 animate (spriteno,action$#) 

0750 movesprite (spriteno, 350,150, 300,0) 
0740 

0770 WHILE KEY$=CHR#¢(0) DO NULL 


We hope that this brief program example will inspire you to 
attempt your own complex dramatizations or games! 


The order of the action is specified in line 730. Trans- 
lating this line we find the following instructions: 
Display drawing 1 for 4 units of time, show drawing 2 for 
units of time. Continue to repeat this action until the 
sprite stops. 


tn 


See the overview under animate for further information on 
order of action sequences. 


A MULTI-COLORED SPRITE 


So far we have only used drawings in high-resolution 
graphics (specified by a ""O0"" in the 

define (<drawingno>,<drawingt>+""0"")) procedure. The 
drawing is in only one color; it can readily be used either 
on a high-graphics screen (graphicescreen(O)) or ona 
multi-color screen (graphicscreen(1)). 


A sprite drawing can de created using several colors, but it 
is a little more complicated to create unless you can use 
the program "Spriteeditor"™ on the demo diskette or tape 
which accompanied your COMAL cartridge. See additional 
information on this program in Appendix H. 


When a sprite image is defined using several colors, it is 
important to keep in mind that the horizontal neighboring 
pixels are associated in pairs when using multi-color 
graphics. In connection with the used of sprites in multi- 
color graphics, the following pairs of numbers determine the 
color of the sprite: 


00 Transparent 

O01 Color 2 

10 Foreground color 1 
11 Color 3 
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Thus a sprite can be composed of 4 different colors, ane of 
which is "transparent". The foreground color is determined 
by the spritecolor procedure. Colors 2 and 3 are 
determined by the spriteback procedure. 


Just as with drawings in high-res graphics, it is a good 
idea to start by making a plan on graph paper. Pair the 
horizontal pixels when choosing the four possible "colors". 
Then prepare the drawing in the form of DATA statements as 
before. But now you must be more careful when assigning the 
correct number combinations to the pixel pairs. 


Here is a program. (Sprite 3) which uses sprites with 
several colors: 


0010 DATA 2400000000 , 400000000 , 400000000 
0020 DATA 400001010, %00000000 , 400000000 
0030 DATA %00001010, 400000000 , 400000000 
0040 DATA %~00000101 , 401010101 , 401010000 
0050 DATA 400000101 , 401010101 , 401010000 
0060 DATA %00000101 , 401010101 ,%01010000 
0070 DATA %00001010,%10101010, 410100000 
0080 DATA %00001010,%10101011,4%11100000 
0090 DATA %00001000, 400101011 ,%11100000 
0100 DATA %00001000, 400101011 ,411100000 
0110 DATA %00001000 , 400101011 ,%11100000 
0120 DATA %00001000 , 400101011 ,%11100000 
0130 DATA %00001000, 400101001 , 411100000 
0140 DATA 7~00001010,%10101011,%11100000 
0150 DATA 2£00001010,410101011,411100000 
0160 DATA Z400001010,2%10101011,%11100000 
0170 DATA 400001010,%10101011 ,411100000 
0180 DATA 400001010,2%10101011,%11100000 
0190 DATA 411111111,411111101,401111111 
0200 DATA 411111111,411111101,401111111 
0210 DATA 411111111,411111101,%01111111 


0230 USE graphics 

0240 graphicscreen (1) 

0250 USE sprites 

0260 DIM drawings OF 64 
0270 FOR it=1 TO 63 DO 
0280 READ byte 

0290 drawings: +CHR$ (byte) 
0300 ENDFOR i 


0320 drawingno:=1 
0330 define (drawingno,drawings+""1"") 
0340 background (0) 
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O3S50 spriteback (2,12) 

0360 RANDOMIZE 

0370 FOR spriteno:20 TO 7 DO 

0380 spritecolor (spriteno,RND(3,10)) 
0390 spritepos (spriteno,spriteno#40,50) 
0400 identify (spriteno,drawingno) 

0410 showsprite (spriteno) 

0420 spritesize(spriteno,1,1) 

0430 ENDFOR spriteno 

0440 FOR is#1 TO 100 DO plot (RND (0,319) ,RND(50,199) ) 
0450 WHILE KEY$S=CHRS#(0O) DO NULL 


In line 240 multi-color graphics is selected. In line 330 
the drawing is defined as a multi-color image by means of 
the ""1"" in the procedure call. 


In line 340 the graphics screen background color is 
selected. In line 250 the 2nd and 3rd colors for the sprites 
are chosen. 


In line 280 a random foreground color is chosen for each 
sprite. In line 420 all sprites are set double size. In 
line 440 stars are placed in the sky. 


SPRITE OVERVIEW 


The package sprites contains 22 procedures and functions. 


Definition of drawings and sprites: 


define (<drawingno>,<drawing$>) 

identify (<spriteno>,<drawingno>) 
Sprite color (s): 

spritecolor (<spriteno>,<color>) 

spriteback (<color2>,<colors>) 


Sprite sizer 
spritesize(<spriteno>,<xdouble>,<ydouble>) 


Sprite position and motions 

spritepos (<spriteno>,<x>,<y>) 

movesprite (<spriteno>,<x>,<y>,<step>,<mode>) 

startsprites 

stopsprite(<spriteno>) 

moving (<spriteno>) 

spritex (<spriteno>)- 

spritey (<spriteno>) 

animate (<spriteno>,<action$#>) 
Visibilitys 

showsprite(<spriteno>) 

hidesprite(<spriteno>) 

priority (<spriteno>,<graphics’in’front>) 
collisionscheck: 

spritecollision(<spriteno>,<yes/no>) 

datacollision (<spriteno>,<yes/no>) 


Information about sprites: 
spriteing (<spriteno>,<property>) 


A_ sprite is transformed into a graphics drawing: 
stampsprite(<spriteno>) 
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Sprite images and storage: 


saveshape (<drawingno>,<filenames>) 
loadshape (<drawingno>,<filenames>) 
linkshape (<drawingno>) 

(Use cst in file name for Datassette file.) 


define (<drawingno> ,<drawing$s>) 


is a procedure which defines a new drawing. The 
variable <drawingS> is a string with a length of 64 
characters. It contains the information which 
specifies the sprite image. (See the examples at the 
beginning of this section.) The image defined is 
assigned the number given by the parameter 


<drawingno>. @ 


There can be up to 32 images defined at one time. The 
parameter <drawingno> must be an integer between 0 

and 31. The same image may be used to identify several 
different sprites. 


Example: 


define (23,house$) The contents of the string house$ 
defines drawing number 23. 


identify (<spriteno>,<drawingno>) 


is a procedure which specifies that the sprite with the 
number <spriteno> is to be displayed using the image 
with the number <drawingno>. There can be up to 8 
different sprites on the screen at once. The parameter 
<spriteno> must be an integer from 0 to 7. The same 
drawing can form the basis for several sprites. 


The sprite with the lowest <spriteno> has the highest 
priority and is therefore displayed in front of others 
with which it overlaps on the screen. 


If the graphics turtle is displayed on the screen, it 
always has sprite number 7. 


Example: } 


identify (0,23) Sprite number O is displayed as 
image no 23. 


spritecolor (<spriteno>,<color>) 


is a procedure which assigns the sprite with the number 
<spriteno> the color specified. The parameter 
<spriteno> is an integer from 0 to 7, and <color> 

is an integer from O to 15. In high-resolution 
graphics the sprite will have this color. In multi- 
color graphics it is colorl. 


Example: 


spritecolor (0,8) Sprite number O is given color number 8. 
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spriteback (<color2>,<colors3>) 


is a procedure which specifies the colors in multi- 
color graphics. A multi-color sprite can have up to 
four colors: 


transparent (but does not cover other colors) 
foreground color set with pencolor (=color1) 
additional colors set with spriteback (=color2 and 
color) 
Examples: 
spriteback (2,7) additional colors are red and yellow. 
Special rules for Multi-colored Sprites: 





In a multi-color drawing pixels are associated in 
horizontal pairs. Each color (background-, foreground— 
and additional) is indicated by bit patterns as 
follows: 


Bit Color shown Is set by 

pair 

00 transparent graphics orders 
O1 color 2 spriteback 

10 color 1 spritecolor 

11 color 3 spriteback 


If graphics has priority over sprites (e.g. 
priority (<spriteno>,TRUE)), then color2 with bit 
pattern O1 will also be the background color. 


The parameter color2 gives no report about collision 
with another sprite (spritecollision) or with 
graphics drawings (datacollision). 


spritesize(<spriteno>,<xdouble>,<ydouble>) 


1S a procedure which determines whether the sprite 
numbered <spriteno> will be displayed in double size 
format. Normally a sprite otcupies 24 pixels in the 
x-direction and 21 pixels in the y-direction. If 
<xdouble> is set equal to a number not equal to Q 
(=TRUE), then the sprite will be shown in double 
width. Similarly for <ydouble>. 


Examples: 
spritesize(5,0,1) Sprite 5 double height 


spritesize(2,TRUE,TRUE) Sprite 2 double size 


spritepos (<spriteno>,<x>,<y>) 


is a procedure which places the upper left-hand corner 
af the sprite at the point with screen coordinates 
(x,y). 


Sprite positions are always specified in the screen 
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coordinate system independent of any other coordinate 
system which may have been defined by the graphics 
order window. Sprite coordinates are in fact 
specified in the coordinate system (-32768..32767, —- 
32768. .32767). Only the points (0..319,0..199) are 
visible on the screen. 


Examples 


spritepos(0,25,50) Sprite O is placed at screen 
position (25,50). 


movesprite(<spriteno>,<x>,<y>,<step>,<mode>) 


is a procedure which moves the sprite numbered 
<spriteno> from the current position to the point 
(x,y). The motion is performed in <step> small 

steps. Each step takes 1/50 of a second on computers 
using the European PAL standard. On computers using 
the American NTSC standard, each step takes 1/60 of a 
second. The time in each case corresponds to the time 
it takes to update the screen image. 


The parameter <step> expresses how many time 
intervals (screen updates) the movement will take. The 
fewer the number of steps, the faster the motion. 


The parameter <step> determines the speed of the 
sprite as follows: 


1. If <step> is held constant, then the speed 
will always be proportional to the distance 
between the two endpoints of the motion. 


2. the speed will be independent of the distance 
between the endpoints if <step> e.g. is 
defined by: 


FUNC step (spriteno,x,y) 
speed: =10 
dxs=x-spritex (spriteno) 
dy: *y-spritey (spriteno) 
dist: =SQR (dx #dx+dy#dy) 
RETURN speed*dist 
ENDFUNC step 


If this function is used to determine the 
parameter step, the speed will always be 
constant. In this case about 1 screen time 
unit. 


>. the speed can made incependent of the x—- 
distance (similarly for the y-distance), so 
that the sprite will appear to move with 
constant speed in one dimension. 


This can be assured if <step> is determined 
by the following function. 
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FUNC step (spriteno, x) 
speed: #10 
dist: ABS (x-spritex (spriteno) ) 
RETURN speed+#dist 

ENDFUNC step 


If in particular step equals 0, the sprite will be 
moved immediately (next screen update) to the position 
(<x>,<y>) regardless of the value of <mode>. The 
sprite will not move again, but it can be caused to 
perform an action by using the procedure animate. 


The parameter <mode> affects the moment when the 
movement begins, and determines whether or not 
collision with other sprites and graphics drawings will 
be taken into account. The parameter <mode> is an 
integer from O to 7: 


<mode> effect 

Oo Start now, no collision check 
1 Await start signal, no collision check 
2 Start now, check sprite/sprite collision 
= Await start signal, check sprite/sprite collision 
4 Start now, check sprite/graphics collision 
a) Await start signal, check sprite/graphics collision 
& Start now, check for any collision 
7 Await start signal, check for any collision 

Note: 


The procedure movesprite starts the motion. The 

COMAL system does not wait for the motion to stop but 
continues with the next line in the program. This 
makes it possible to start other sprites in motion, 
print messages, etc. Many things can be going on at 
the same time. If you do not want program execution to 
continue while the motion is carried out, you can adda 
“wait’ line. For example: 


WHILE moving (<spriteno>) DO NULL 
or 
WHILE NOT datacollision(<spriteno>, TRUE) DO NULL 


Examples: 


movesprite(2,200,130,100,0) Move sprite no 2 to the 
point (200,130) in 100 
screen updates. Start now 
with no collision check. 


movesprite (0,250,-10,300,6) Move sprite no O to the 
point (250,-10) in 300 
steps. Start now, check-— 
ing for sprite collisions 
and collisions with 
graphics drawings. 
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startsprites 


is a procedure which initiates the motion of those 
sprites which are waiting for the start signal. See 
the movesprite procedure. 


stopsprite(<spriteno>) 


is a procedure which stops the motion of the sprite 
with the number specified. 


moving (<spriteno>) 


is a function which takes on the value TRUE (=1) if the 
sprite specified moves. Otherwise the value of 
function is FALSE (=0). 


Examples 
IF NOT moving(2) THEN movesprite(2,0,190,50,0) 


If sprite 2 isn’t moving, then it should be moved at 
once to screen coordinates (0,190). 


spritex(<spriteno>) and spritey(<spriteno>) 


are functions which have the current x- and y-positons 
respectively as vaiues. 


Examples: 


x ‘difference: *x-spritex (4) 
y ‘difference: =y-spritey (4) 


IF spritey (3) >200 THEN movesprite(3,spritex (3) ,20,200,0) 


If sprite no = collides with the upper edge of the 
screen, then it ‘falls’ to the lower edge. 


animate (<spriteno>,<action$>) 


is a procedure which causes the sprite specified to 
automatically perform a given action. The action 
desired must be defined in the string <action$>. 


The number of characters in the order of action 
specification must be an even number (maximum 64). 
Thus a maximum of 32 actions can be requested in each 
<action$> string. 


Possible actions: 


CHR$ (<drawingno>) +CHR$(<time>) the drawing with the 
number indicated should 
be displayed for the 
time specified. 


Note that O<= <drawingno> <=31 and O<= <time> <=255 
units of time (screen updates). See the procedure 
movesprite for more about timing. 
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If <time> is equal to O, the sprite will enter a 
wait state which can only be interrupted by the order 
startsprites or by a "g"-action. 


"p"+CHRS (<time>) Pause for the given time 
interval. 

"g"+CHRS (<spriteno>) Restart the given sprite, 
if it is waiting. 

"s"+CHRS (<spriteno>) The specified sprite is 
shown. 

"h"+CHRS (<spriteno>) The specified sprite is 
hidden. 

"x "+CHRS (<xdouble>) If <xdouble> is TRUE 


(i.e. < > O) the width of 
the sprite is doubled. If 
<xdouble> is FALSE (i.e. 

= 0), the sprite is 24 
pixels wide. 


“y"+CHRS (<ydouble>) Analogous to 
"x "+CHRS (<xdouble>). 

"c"+CHRS (<color>) The sprite acquires the color 
indicated, where O<= <color> 
<=15. 


The action must be started by the procedure 

movesprite. The actions specified by the string are 
carried out from left to right unless the sprite is in 
a wait state. When the last action has been completed, 
the sequence is repeated until the sprite is no longer 
in motion: either the movesprite motion is finished, 

Or an animate(<spriteno>,"") order is executed. 


Just as with the movesprite procedure the COMAL 

system does not wait for the action sequence to be 
completed but procedes directly to the next line in the 
program. 


Note that CHR$(<value>) has the same meaning as 
"“"€value>"", so 


action$: ="s"+CHRS$ (1) +"p"+CHRS (10) +"h" +CHRS (1) +"p"+CHRS$ (10) 
is identical to 


action$: atte” 1 "D 0 10"h" 1"p a 10" a 


Exampleas 

animate (1, "s"1"p"1O"H"1"p"10"") Sprite no 1 moves at 
movesprite(1,100,100,0,0) once to the screen 
WHILE KEYS$=CHRS$ (0) DO NULL position (100,100) and 
animate(1,"") flashes for 10 time 


units, until any key 
is pressed. 
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ani mate(S, 0 “a " “au aa “gu a a “an “y 
movesprite (3,500, 180,500,0) 


While sprite no 3 moves to screen position (300,180), 
it is first shown for 4 units of time as drawing no 1. 
Next it is displayed for 4 time units as drawing no 2, 
followed by drawing no 3. The sequence is then 
repeated again. Animation! 


showsprite(<spriteno>) 


is a procedure which makes the specified sprite visible 
(if it is on the screen). 


hidesprite(<spriteno>) 
is a procedure which conceals the sprite. 
priority (<spriteno>,<graphics ‘in ’front>) 


is a procedure which determines the priority of the 
specified sprite in relation to the graphics drawings 
on the screen. If <graphics’in’front> has the value 
TRUE (=1), the graphics will be displayed in front of 
the sprite when they overlap. If the value is FALSE 
(=O), the sprite will appear in front of the graphics. 
When USE sprites is first used, the value is 
automatically set to FALSE. 


Example: 


priority(4,1) Sprite no 6 will be displayed behind 
graphics. 


spritecollision (<spriteno>,<yes‘no>) 


is a function which is used to specify when the given 
sprite collides with another sprite, or determine if it 
collided with one earlier. 


If <yes’no>=TRUE, then spritecollision is FALSE, 
until a collision occurs. 

If <yes’no>=FALSE, then spritecollision is TRUE, if 
a collision has already occured. 


Collisions occur when colors different from the 
background color overlap. See in particular the remark 
under the spriteback procedure concerning multi-color 
graphics. 


Examples: 
WHILE NOT spritecollision(2, TRUE) DO NULL 


Do nothing before sprite no 2 collides with another 
sprite. 


IF spritecollision(4,0) THEN spritecolor (4,2) 


If sprite no 4 has previously collided with another 
sprite, then it should be colored red. 
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datacollision (<spriteno>,<yes‘no>) 
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is a function which is used to determine when the 
specified sprite collides with graphics drawings, or if 
it previously has collided with graphics drawings. 


If <yes’no>=TRUE, then datacollision is FALSE until 


the collision occurs. 


If <yes’no>=FALSE, then datacollision will be TRUE 
if a previous collision has occured. 


A collision takes place when colors different from the 


background color overlap. 


spriteing(<spriteno>,<property>) 


(See spritecollision.) 


is a function which is used to obtain information 


concerning the sprite specified. 


The value of the 


parameter <property> determines which characteristic 


is to indicated. 


<prop- The function 
erty> 

QO visible 

1 Multi-color2 (O01) 

2 Multi-colori (10) 

> Multi-colors3 (11) 

4 double width 

ra double height 

& Multi-color 

7 gra./sprite priority 
8 drawing number 

9 time remaining 

10 sprite/sprite collision 
11 sprite/gra. collision 
12 mode of motion 

13 number of actions 

14 no. of next action 


Range 


TRUE/FALSE 
0.215 
0..15 
0O..15 

TRUE /FALSE 
TRUE/FALSE 
TRUE/FALSE 
TRUE /FALSE 
O..S1 
0..215 
TRUE /FALSE 
TRUE /FALSE 
0O..7 

0..32 


0..52 


Is set with 


hide/showsprite 
spriteback 
spritecolor 
spriteback 
spritesize 
spritesize 
define,identify 
priority 
identify 
movesprite 
movesprite 
movesprite 
movesprite 
animate 

animate 


Note that TRUE and FALSE have the numerical values 1 and 


Oo. 


Examples: 


FOR no:#1 TO 14 DO PRINT spriteing (no) 


stampsprite(<spriteno>) 


is a procedure which is used to change the sprite into 


a graphics image. 
graphics screen image. 


The sprite is "stamped" onto the 


Normally a sprite is not part of a graphics illustra-— 
tion and will therefore not be printed out with the 
rest of the graphics when the procedures printscreen 
and savescreen are used. The procedure stampsprite 
makes a copy of the sprite part of the graphics screen 


image. 


This procedure can be employed e.g. 


if you wish 
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to incorporate the graphics turtle as part of a drawing 
which is to be saved or printed. 


Examples 
FOR spriteno:=7 TO O STEP -1 DO stampsprite(spriteno) 


Copies of all visible sprites: are made on the graphics 
screen. 


saveshape (<drawingno>,<file name$>) 


is a procedure which saves a copy of the sprite image 

on diskette or tape (remember cs: in the file name) 

under the name <filename$>. The drawing itself must & 
be represented by a string 64 characters in length. 


Example: 


define (2,drawing$s) The figure contained in the 
saveshape(2,"sp0.flower") string drawing, is saved 
under the name "sp0. flower". 
The O is included in the name 
to indicate that the drawing is 
intended for use in high- 
resolution graphics. 


loadshape (<drawingno>,<filename$>) 


is a procedure which fetches a copy of the file named 
<filename$> from diskette or cassette tape. The file 
must have been saved previously using the procedure 
saveshape. The file <filename$> must contain a 
string with the definition of a sprite image. This 
drawing will be given the number <drawingno>. 


Example: 


loadshape (1, "sp0.flower") The file spoO. flower 
contains a string with an 
image which will be 
recognized as number 1 © 
in the program. 


linkshape (<drawingno>) 


is a procedure which associates a copy of the drawing 
indicated with the COMAL program. When the program is 
saved using the order SAVE, the drawing will be saved 
with it. It can be read in later together with the 
program with the order LOAD. 


If desired, the drawing can be disassociated from the 
COMAL program by using the order DISCARD. 


The drawing must have been fetched earlier using the 
procedure loadshape. This drawing is assigned the 
number <drawingno>. 
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Examples: 


Llinkshape (7) The drawing with the number 7 is 
associated with the COMAL program in 
working memory. 
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SOUND AND MUSIC 


Those of you who are familiar with the sound capabilities of 
the Commodore 44 will be pleased to know that your COMAL 
cartridge offers you full and easy access to the Commodore 
6581 sound synthesizer (SID) chip. This chip allows you 
to use up to three musical voices at the same time. In 
addition you have considerable freedom ta decide how the 
individual notes will sound. You can control frequency, 
sound level, sound type, modulation and filtering. This 
section must be considered to be only an introduction to a 
very exciting subject. An entire book could be devoted toa 
the study of music synthesis using the Commodore 64. 


Using the COMAL order 
USE sound, 


you make a number of additional procedures and functions 
available. Use these procedures and COMAL programming to 
create your own "orchestra". 


Individual notes are denoted by strings. For example, 
"middie C" on the musical scale is denoted by the string 
Variable "c4"., 


The other notes in this octave are denoted: 

"c4","c40" ,"d4","d4e", etc. Notes in the next highest 
octave are denoted By "c5","cS#" and so on. The notation 
for the next lowest octave is "c3","c3#",.... Notice that 
sharp notes are denoted "f4#" for "f-sharp" in the fourth 
octave, etc. 


Although this tutorial is not intended to be a music course, 
here area few facts which may be helpful when transfering a 
musical score to your Commodore 44. You will have to 
identify the notes and their durations. The following 
figure shows the ordering of some of the notes which can be 
played and the standard musical symbols for note duration: 


d 
’ 
; 
aA 





The full range of notes starts with "cO" and extends up to 
and includes "a7#@" on computers with European PAL 
standard, and "b7" on computer with the American NTSC 
standard. . 
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In this section we will comment briefly on six programs, 


which you 


will find on the demonstration diskette or tape. 


You will find complete printouts of these programs in 
Appendix H. They are titled as follows and have the 
contents indicated below: 


Music Demo: You will probably want to start by running 


this 


program to get an idea of the capabilities of your 


COMAL sound package. After examining the programs of 
lessons 1-5, you can return to study this program to 
see how all three voices can be used together. 


Music 1: This program illustrates how individual notes are 
played. 
_ ‘Music 2: Up to three musical voices are available. It is 


possible to use up to three notes at the same time in 


your 


programs, giving your compositions a rich and 


realistic dimension. 


Music 3: 
own 
the 


Here you can hear a demonstration or make your 
composition using just one voice. Again, listing 
program will be helpful to help you learn how to 


write your own music programs. 


Music 4: 


This demonstration program allows you to change a 


number of parameters which affect the sound of each 
voice: volume, soundtype and the adsr 
(attack-decay-sustain-release) waveform envelope. 


Music 53: 


Here is a complete composition illustrating 


synchronized music with several voices. 


After trying out the Music Demo, you will probably want to 


LOAD, RUN 


and LIST each of the five "Music" programs. 


Notice that the order USE sound must appear in a program, 
before the sound control orders will be active. In the 
listing for Music 1 pay particular attention to lines 


150-320: 


0150 
0160 
a 0170 
0190 
0200 
0210 
0220 
0230 
0240 
0250 
0260 
0270 
0280 
0290 
O300 
0310 
0320 


The first 


INPUT AT 6,13: "voices ": voice 
INPUT AT 9,13 "note-code: "scodes 
play (voice,code$) 


PROC play (voice,code$) 
IF codes<>"z" THEN 
note (voice,codes$) 
gate(voice,1) // attack & decay 
ENDIF 
delay(2) // sustain 
gate(voice,O) // release 
ENDPROC play 


PROC delay (sec ’32) 

TIME 

WHILE TIME<1.9875*sec ’S2 DO NULL 
ENDPROC delay 


thing that happens are the INPUT statements. The 


voice number (1, 2 or 3) and the note code (c0O,cO#,... 
or a7#) are to be entered here. In line 170 the sound 
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procedure play is called with these two variables as 
inputs. 


If the note code variable code# is a “z", no new note 

will be played. Use "z" when you want a pause to occur in 
your music. It must be followed by a duration code, just 

like a note. If code# is a legal note code, then the note 
will be played. 


This is accomplished as follows. The procedure 

note (voice,code$) sets up the voice and the note, getting 
it ready to be played. The preccedure gate(voice,1) 
initiates the playing of the note; the attack and decay 
portions of the adsr envelope are executed at once. The 
procedure delay (which must be provided by the user) 
determines the length of time the note is sustained. 
Finally, the order gate(voice,O) terminates the sustain 
phase and the note procedes to decay, as specified by the 
adsr procedure. More on adgsr later! 


The user supplied delay procedure can be any routine which 
can use up a well-defined time interval. In this program we 
have done this by means of a WHILE...DO loop which does 
nothing (NULL). The procedure call pause(14) in line 250 
causes a delay of 16/32 = 1/2 second. 


To make two notes play simultaneously, instructions like the 
following must be added: 


225 note(2,"c5") 
235 gate(2,1) 
265 gate(2,0) 


Try LGADing, RUNning and LISTing Music 2. You will find 
the procedures play and delay used again. In addition 
you will find the following instructions: 


0130 FOR voicer#1 TO 3 DO 

0140 soundtype (voice, 3) 

0150 ENDFOR voice 

0160 . 
0170 INPUT AT 7,1: "note-coder “: codes 
01860 

0190 FOR voices#1 TO 3 DO 

0200 PRINT AT 10,1: “voice "js voice 
0210 play(voice,code$) 

0220 play (voice,"z") 

0230 ENDFOR voice 


Lines 130-150 are used to set up the soundtype of each of 
the three voices. This is a sound package order with two 
input variables. The first variable is the voice number 

(1,2 or 3), and the second one is the soundtype (0,1,2,3 

or 4). These numbers specify soundtypes as follows: 


gsoundtype O: silence 
gsoundtype is triangular wave 
soundtype 2: sawtooth wave 
soundtype 3: square wave 
gsoundtype 4: white noise 
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It will require some experience before you become skillful 
at selecting the best soundtype to achieve the effects you 
want. Lines 130-150 in this example set all three voices to 
the square wave soundtype. 


Line 170 inputs a note code. Lines 190-230 allow the note 
to be played using all three voices, so that you can 
experience the differences among them. Notice that the 
procedure play(voice,code$) is used just as it was used 
earlier. Notice also that we have used "z" as an input to 
Play to achieve a pause between the playing of each note. 
Try removing line 220 and listen to what happens when the 
program is run. 


Now LOAD and RUN the program Music 3. LIST it, and pay 
particular attention to lines 330-500: 


O330 PROC play‘’melody // Row, Row, Row Your Boat 
0340 

03350 melody: 

0360 DATA "c4" 8, Wet ses Hea <6; to ‘25 wea 58, “qa 4 
0370 DATA "e4",8,"z",8, "a4" ,8,"d4",4,"2e4",8 
0380 DATA "44",4,"9g4",16,"2",8,"c5",4 

0390 DATA "c3",4,"c5",4,"9g4",4,"94",4 

0400 DATA "g4",4, "#4" ,4, "2824" ,4, "84" ,4 

0410 DATA “c4",4,"c4",4,"c4",4,"2z",8,"9g4",8 
0420 DATA "€4",4,"284",8,"d4",4,"c4",8 

0430 

0440 RESTORE melody 

0450 WHILE NOT EOD DO 

0460 READ code¢,sek ‘32 

0470 play (voice,code$) 

0480 ENDWHILE 

0310 

03520 ENDPROC play ‘melody 


This procedure plays a simple tune (Row, Row, Row your 
Boat): 





The procedure starts by zeroing the DATA pointer (RESTORE 
melody), so the DATA statements are read from the beginning 
each time the melody is played. The lines of DATA contain 
pairs of information (note codes and their durations). Lets 
take a quick look at the data to see how it relates to the 
simple piece of music in this illustration. 


Look at the music. The first note is "middle C™ with the 
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note code c4. It is a quarter note. If we decide to give 
a whole note a duration of 32, then the quarter note must 
be given a duration of 8. The first two data elements are 
"c4".6. Notice that the first element is a string 

variable, while the second element is an integer. After 
the first note we want a brief pause, so the notes don’t all 
run together. We enter “z2",2 to accomplish this. The 

next two notes are also middle C, so they are entered in the 
same way. The vertical line in the musical score indicates 
a brief pause, so we have entered a "2",8 for this 

purpose. Notice that it is not always necessary to enter a 
pause between notes. You must experiment until you 
understand how to achieve the effect you want. 


There are many ways of handling the music data. You could 
enter lines of music as long strings of data and design a 
procedure to "pick out” the note codes and delays one ata 
time. You might choose to make the duration codes integer 
variables to save memory when composing a lengthy piece. If 
sections of the music are repeated, then it will be a 
distinct advantage for you to design each unique section of 
the music as an independent procedure. A "master procedure" 
can then be written to play the piece, executing each 
section in turn. 


The actual playing of the notes is accomplished in lines 
450-480. Data is entered a pair at a time (note code and 
duration). The note is played by play(voice,code$). And 
this. process continues until there is no more data (EQD is 
TRUE). 


Turn now to Music4. This program will help you to 
experiment with a few more orders from the sound package. 
The following lines are of particular interest: 


0180 INPUT AT 11,13 "VOICE (1/2/3)7 ": voice 

0190 INPUT AT 13,1: "VOLUME (0-15)? "s: vol 

0200 INPUT AT 15,1: "SOUNDTYPE (1/2/3/4)7 ": type 
0210 soundtype(voice,type) 

0220 volume (vol ) 


0420 INPUT AT 21,18 "A,D,&,R? "ss a,d,s8,r 
0430 adsr (voice,a,d,s,r) 

0440 

0450 play’ melody 


Lines 180-200 input the voice number, music volume and 
the soundtype for the voice selected. The package 
procedure volume(vol) can be used to regulate the volume 
from silence (0) to the maximum value (15). 


In line 4350 the user can select the waveform parameters. 
These determine the shape of the sound intensity pattern 
‘which forms the note. The actual sound consists of waves as 
specified by the soundtype procedure. The adsr 

procedure allows the user to control the shape of the 
“envelope” governing how the note rises in intensity 
(attack), decays, is sustained at a certain level then 

dies away (release). Notice that the duration of the 
sustain phase of the note is regulated by means of the user 
procedure delay. The shape of the envelope is specificed 
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by the following numbers, each of which can be chosen freely 
in the range from O-15: 


attack specifies the rate at which the waveform 
envelope rises. This rate should be high (i.e. 
the attack parameter small) to achieve a "piano", 
“banjo” or "harpsicord” sound. The sound of 
Plucked stringed instruments is charaterized by a 
very audible attack phase when the note is struck. 


decay determines how fast the note dies down to the 
sustain level. Varying this number will vary the 
type of stringed instrument, you want to emulate. 


sustain defines the intensity level at which the note 
will be played for the delay period specified by 
the user’s delay procedure. 


release regulates how fast the note “dies away" at the 
end of the sustain period. 
Sustain 


Mn 


The last program, Music 53, illustrates how several voices 
can be played at once using the procedure playscore. In 
this example only one voice is used (voice 1). We will see 
later how this can be changed by adding a few more lines. 





The notes should first be read in and transformed to 
frequency values by means of the function frequency. All 
these numbers are then stored in a table of integers 
tone#() along with the associated duration data: an 

ads ‘pause for the attack-decay-sustain phase and an 
r‘pause for the release phase (including the delay between 
notes). The numbers are brought into the voice 1 register 
by means of the procedure setscore. Then the playing is 
initiated by the procedure playscore. 


While the melody is played, the following COMAL program 
prints out some numbers. This is done here simply to 
illustrate that while the SID chip is at work playing music, 
the processor can proceed with other tasks. When the 
background music is finished, the function waitscore takes 
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on the value TRUE (=1). Thus the printing of numbers in the 
WHILE-ENDWHILE loop will stop when the music stops. 


0090 no:2#0 

0100 WHILE NOT EOD DO 

0110 nor+i 

0120 READ codes,tim 

0130 tone# (no) : #=frequency (codes) 
0140 ads ‘pause# (no) :2tim#2 

0150 r’pause# (no) :=timt2 

0160 ENDWHILE 


0180 tone#(nr+1) 3:20 

0190 setscore(i,tone#() ,ads ‘pause#() ,r ‘pause#()) 
0200 playscore(1,0,0) 

0210 

0220 number : #0 

0230 WHILE NOT waitscore(1,0,0) DO 

0240 number: +1 

02350 PRINT number 3 

0260 ENDWHILE 


Add the lines: 


192 setscore (2, tone#() ,ads ’pause#() ,r ‘pause () ) 
194 setscore(S,tone#() ,ads ‘pause#() ,r ‘pause#() ) 


and change lines 200 and 230 to: 


0200 playscore(1,1,1) 
0230 waitscore(1,1,1) 


The three voices will play the melody simultaneously (syn- 
chronized). The program ends, when all three voices have 
finished. 


Can you write a "round" with a delay between the different 
voices”? 


te care eee ee WS ce SD SD eS SS SS SS GS SR SS SS SS ce UN a aie eS SS ED DS A ED Se ee ee a) oD oe 


Notice that when the package if first brought into 
Play with the order USE sound, the following 
default values are selected: 


ader (1,0,4,12,10) 

adgr (2,10,8,10,9) 

adsr (3,0,9,0,9) 

FOR voice:#1 TO 3 DO 
pulse voice,2048 
setfrequency (voice,0O) 

ENDFOR voice 

volume (15) 

soundtype(1,1) // piano 

soundtype(2,2) // violin 
soundtype(3$,3) // cymbal 


ee cme wee ce ce ce ee ce cme cn ee ee ee ee ce ee ec ee ee ee ee ee ee ee ee ee es ee ee ew a ee 


The intention of the five introductory music programs 
has been to acquaint you with how to control the sounds 
created by the sound package. At first you may feel 
that there is a great deal to learn before you can 
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compose music. This is true. But as with many other 
Situations, a skill worth learning does take time and 
effort. Be patient, experiment and be curious. As you 
solve each problem which arises, you will learn 
something new! 


We conclude this section with a summary of the orders 
made available when you invoke the sound package: 


volume (<level >) 

note (<voice>,<code$>) 

gate (<voice>,<start ‘stop>) 
soundtype(<voice>,<soundtype>) 

adsr (<voice>,<attack>,<decay>,<sustain>,<release>) 
setscore (<voice>,<frequency () >,<pausel () >,<pause2 () > 
playscore (<voicel>,<voice2>,<voice3>) 

stopplay (<voicel>,<voice2>,<voices3>) 

waitscore (<voicel>,<voice2>,<voices>) 

frequency (<code$>) 

setfrequency (<voice>,<frequency ‘value>) 

sync (<voice ’combination>,<yes ‘no>) 

filterfreq (<frequency ’value>) 

filter (<voicel>,<voice2>,<voicesS>,<external >) 
filtertype (<low>,<band>,<high>,<S-interrupt>) 
pulse (<voice>,<pulse’width>) 

ringmod (<voice’combination>,<yes ‘no>) 

resonance (<degree>) 

envs 

oscsS 


SOUND ORDERS IN DEPTH 
volume (<level >) 


is a procedure which controls the common sound level 
for all three voices. The parameter <level> is an 
integer from O to 15. 


Examples 
volume (15) maximum sound level 
note (<voice>,<codes>) 


is a procedure which is used to indicate the tone 
<code$> which the voice with the number <voice> 

will play. The parameter <voice> can be 1, 2 or 3; 
<code#> is a string with possible values: "co", 

"cO#" ,"doO",...,"a7#" On machines using the European FAL 
standard. On machines using the American NTSC standard 
tones up to "b7" can be played. The letters in each 
note code indicate the note, and the number indicates 
the octave. The character @ indicates half notes 


(sharp notes). 
Examples 


note (2,"d5") voice 2 will play the note d3 
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gate (<voice>,<start ‘stop>) 


is a procedure which either starts or stops the playing 
of voice number <voice>. If the parameter 

«start ’stop> equals 1, the note starts. If 
<start‘stop> equals O, it stops. 


Example: 
gate(S,1) Voice 3 starts playing. 
soundtype (<voice>,<soundtype>) 


is a procedure which is used to indicate which 
<soundtype> <voice> is to be. The parameter 
<soundtype> is the periodic base signal which will be 
used to create the notes. It can be any of the 
following: 


<soundtype> O: silence 
13: triangle waveform 
2t sawtooth wave 
3: square wave 
4: white noise 


Examples ‘ 
soundtype (1,3) voice 1 formed with square waves 
adsr (<voice>,<attack>,<decay>,<sustain>,<release>) 


1s a procedure which determines the shape of the 
waveform envelope. See the program, Music 4. Note 
especially that <sustain> indicates a sound level 
from O to the maximum sound level (determined by 
volume), while <attack>, <decay> and <release> 
control the time dependence. 


Value <attack> <decay> and <release>: 


Gs 2 msec & msec 
- Ss - 24 - 
2: 16 - 48 - 
3s 24 = - 72 - 
4: 38 =- 114 - 
a: 96 —- 168 - 
é: 68 - 204 - 
73 BO - 240 - 
8: 100 - 300 - 
Fs 200 - 720° = - 
10: 500 - 1.5 sec 
11: B00 - 2.4 - 
12: 1 sec > _ 
13s Ss = 9 - 
14: oo: = 1S - 
15: 8 - 24 - 


<sustain> can equal O, 1,..., 15 
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Examples 


ader (1,13,13,8,13) voice 1 envelope is specified 


playscore (<voicel>,<voice2>,<voicesS>) 


is a procedure which is used to synchronize the start 
of the voices. Al in the variable position 
corresponding to <voicex> starts the voice playing: 


Example: 


playscore(1,1,0) voice 1 and 2 are started 


stopplay (<voicel>,<voice2>,<voices>) 


1s a procedure which stops the playing of the voices 
indicated. If <voicexX> is TRUE (=1), then voice X 
stops playing. 


Examples 


stopplay(0,1,1) voice 2 and 3 are stopped 


waitscore (<voicel>,<voice2>,<voices3>) 


is a function which returns the value TRUE (=1) if the 
Playing of the indicated voice combination has 
finished. 


Example: 


WHILE NOT waitscore(1,1,0) DO NULL do nothing before 
voice 1 and 2 


have finished 
Playing. 


frequency (<code$s>>) 


is a function which returns the integer value which the 
SID chip must receive to play the note. It is mostly 
used to compute table values for the procedure 
setscore. The integer value lies between -327668 and 
32767 inclusive. It is NOT possble to transform notes 
between octaves directly by dividing these numbers by 
2. The parameter <code$> must contain a string with 

a valid note code (i.e. one of the codes “cO",osv.?. 


Examples 


frequency ("c4") the note "c4" is transformed 
to a number 


setfrequency (<voice>,<frequency ‘value>) 


is a procedure which is used to define the frequency of 
each <voice>. The number <frequency ‘value> must be 

in the range O —- 65535. These numbers do not 
correspond directly to the SID chip frequency codes. 


Chapter 5 - ~ 194- COMAL PACKAGES 


Examples 
setfrequency (2,2000) 
sync (<voice ’‘combination>,<yes ‘no>) 
is a procedure which takes care of synchronization with 
respect to the <voice’combination> indicated if 


<yes’no> equals 1. Otherwize the voice combination 
is not synchronized. 


Notes voice ‘combination corresponds to sync 
number : between voices: 
1 1 and S$ 
2 1 and 2 @ 
3 z2and 3 
Example: 
eync(1,1) voice 1 and 3 are synchronized 


filterfreq(<frequency ‘value>) 
is a procedure which is used to determine the cutoff 
frequency for the filter. The parameter 
<frequency value> must be in the range O to 2047 
inclusive, corresponding to frequencies between about 
=O and 12000 Hz. 
Example: 
filterfreq (1500) 

filter (<voicel>,<voice2>,<voiceS>,<external >) 
1S a procdure which is used to select which voices are 
to be filtered, i.e. damped. Alina <voiceXx> 
position means that voice X is to be filtered. 


Examples 


filter (0O,1,1,1) voice 1 should NOT be filtered 





filtertype(<low>,<band>,<high>,<3’interrupt>) 
is a procedure which is used to select the filter type. 


If <low> equals 1, then a ‘low-pass’ filter is 
used, damping tones in the treble range. All 
frequencies above the filter frequency (set by 
filterfreq) are damped 12 dB per octave. 


If <band> equals 1, then damping occurs on both 
sides of the filter frequency; 6 dB per octave. 


If <high> equals 1, then the low frequencies are 
damped by 12 dB per octave. 


If <3’interrupt> equals 1, then voice 3 will not be 
audible. It can be used to code information about 
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synchronization and ringmodulation. 
Several filters can be selected at the same time. 
Exampler 


filtertype(1,0,1,0) creates a “notch filter" 
which has the opposite effect 
of a “band-pass filter": 
damping occurs around the 
filter frequency. 


pulse (<voice>,<pulse’width>) 


is a procedure which is used to indicate the ratio 
between the time during which a square wave is high and 
the time during which it is low (the "duty-cycle"). 

The more this ratio deviates from 1:1, the more "nasai" 
and "sharp" the sound will be. The parameter 
<pulse’width> is a number from © to 4096 inclusive. 
When selected as 2046 the ratio is 1:1. 


Examples 


pulse (11,2948) The ratio high/low equals 1. 


ringmod (<voice ’combination>,<yes ‘no>) 


is a procedure which is used to determine whether ring 
modulation is to be in effect. The parameter 
<voice’combination> selects which voices are affected 
(see sync). If <yes’no> is TRUE (=1) modulation 

will occurs; it will not if Cyes’no> equals FALSE 

(=0). 


When ring modulation is in effect, then two new voices 
with frequencies equal to the sum and the difference 
between the original voices are generated. 


resonance (<degree>) 


is a procedure which is used to indicate to what degree 
certain frequencies will be emphasized. The greater 
the value of the parameter degree, the greater the 
emphasis on the frequencies selected by the procedure 
setfrequency will be. This will give the sound a 
synthetic quality. The parameter <degree> must be an 
integer from O to 15. 


envs 


is a function with no parameters. It returns the 
amplitude of the intensity envelope for voice number 2. 
The values of the function lies in the interval O - 
255. 


Displaying the intensity envelope: 





USE sound 
USE graphics 
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graphicscreen (0) 
volume (10) 
soundtype (3,1) 
note (3,"a4") 
adgr (3,13,13,8,13) 
gate(3,0) 
WHILE env3<>0 DO NULL 
TIME O 
gate(S,1) 
WHILE TIME<40#10 DO 
drawto (TIME/S ,env3/2546%*199) 
ENDWHILE 
gate (S,0) | 
WHILE TIME/S<320 DO 
drawto (TIME/S , env3/256#199) 
ENDWHILE 
WHILE KEYS#CHR$(0O) DO NULL 


osc 


is a function with no parameters. It returns a value 
from O to 255. The number indicates the excursion of 
the current sound type of voice 2. In the case of a 
triangle the numbers vary from O to 255 and back to 0 
again. For the sawtooth wave, values increase from 0 
to 255 then fall rapidly back to 0. The square wave 
pulse varies between O and 255. White noise yields 
random numbers from O to 255. 


em ec cr cr ce ee we ee ce we we me ee we ee we wr ee ee a oe re we ee ees ee a wo ee ee ee 


Note that the sound continues playing after a 
COMAL program stops. The sound stops only if a 
melody is finished, if the COMAL program produces 
an error message or if it communicates with the 
disk drive. These orders all use the 

interrupt, also used by the sound chip. 


em cc me me cre a ce ce wr crn rn me ee re es ee es ee ee es ee ee re ee ee re ee we ee ee oe 
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PACKAGES FOR USING THE CONTROL PORTS 


The COMAL cartridge contains 3 packages which can be used 
with the two input ports (game ports) on the right hand side 
of your Commodore 64 (on the back of the SX-64). These two 
inputs will be refered to as control port 1 


and control port 2. 


The control ports can be used to attach accessories like 
joysticks or paddies. Signals from these devices can be 
interpreted and assigned numbers by the the computer. The 
Commodore 64 can be used with a range of different acces-— 
sories — both commercially available and those you can build 
yourself. (See Chapter 7 on Feripheral Equipment. ?) 


in this section we will deal specifically with: 


paddles 
joystick 
light pen 


These accessories can be 
purchased from your 
Commodore dealer. 


Some of the COMAL pack-— 
ages contain procedures 
which make it easier to 
use these accessories. 





The package paddles is made available by the order: 
USE paddles 


A pair of paddles should be attached to a control port. The 
paddles will be refered to as paddle a and paddle b. 

Each paddle has a knob, which is used to change the 

position of a variable resistor, and a push-button, which 
shorts a port input to ground when activated. 
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The package contains a single procedure: 


paddle (<portno>,<a‘paddle>,<b’paddle>,<a’button>,<b ‘buttoan>) 


which transforms information, from the control port to 
numbers. 


* The parameter <portno> must contain the number of 
the control port to which the paddle pair is 
attached: 1 or 2. 


* The variables <a‘ paddle> and <b’paddile> contain 
the numerical value corresponding to the knob 
position of paddle a and paddle b respectively: 


O<= <a’paddle> <=255 and O <= <b’paddle> <=255 


* The variable <a’button> equals 1 if the a- 
pushbutton is depressed; otherwise <a’button> 
equals O. Similarly for <b’button>. 


Examples 

USE paddles 

paddle(2,a‘paddle,b ‘paddle,a’button,b ‘button) 
PRINT a’ paddie;b ‘paddie;a’button;b ‘button 


The signal values are fetched from control port 2 and 
printed out in the next line. 


The following program example, Paddle Game, is available 
on the demo diskette (tape): 


0010 
0020 
0030 
0040 
0050 
0060 
0070 
0080 
0090 
0100 
0110 


0260 


USE paddles 


DIM formats OF 40 
format$Sr:=" ### ¥ HEH #" 


PAGE 
INPUT AT 2,1: “control port no > “": portno 


DIM winners OF 1 

winner$:=s"c" 

PRINT AT 9,23 “Who can adjust the paddle and press " 
PRINT AT 10,2: “the fire button the fastest?" 

PRINT AT 13,2: "Press a key to start." 

RANDOMIZE 

WHILE KEY$=2CHR#(0) DO NULL 

number : =RND (0, 255) 

PRINT AT 13,2: “The number iss ",number 


REPEAT 

paddle(portno,a’paddle,b ‘paddle,a‘button,b button) 

PRINT AT 3,1: " a’paddle a‘button b’paddie b‘button" 
PRINT AT 6,1: USING format$: a‘paddile,a‘button, 

b ‘paddle,b ‘button 


IF number=#a‘paddle AND a‘button THEN winners:="a" 
IF number=b ‘paddle AND b’button THEN winners:="b" 
UNTIL winners IN “ab" 
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0270 
0280 PRINT AT 17,2: winners+" was fastest!" 


JOYSTICKS 


The package joysticks becomes accessible when you use the 
order: 


USE joysticks 
Attach a joystick to one of the control ports. A joystick 


is a peripheral device which can be centered or moved by the 
user into any of 8 different positions: 


Direction COMAL. — number 
up 1 
up-left up-right 8 2 
left neutral right 7 | 3 
down-left down-right 6 4 
down ra 


In addition there is a push-button on the joystick (the fire 
button) which sends a signal to the computer when pressed. 


The package contains a single procedure: 
soystick (<portno>,<direction>,<button>) 


which translates the signals from the joystick to 
Numerical values for use in programs. 


* <portna> must contain the number of the port to 
which the joystick is attached: 1 or 2. 


* <direction> is a variable which equals a number in 
the range O - 8. These values indicate the 
position of the joystick. See above. 


* €button> is a variable with the value 1 when the 
fire button is pushed, otherwize <button> equals 


QO. 
Examples. 
USE joysticks The signal values are fetched 
jJoystick(2,retning,button) from control port 2 and printed 
PRINT direction; button in the next line. 


The program example shows how a joystick can be used to draw: 
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0100 PAGE 

0110 PRINT “JOYSTICK FOR DRAWING" 

0120 PRINT 

0130 PRINT "The joystick determines drawing direction." 
0140 PRINT "The fire button switches colors." 

0150 PRINT 

0160 PRINT "Press <STOP> to stop the progran." 

0170 PRINT "Press <f5> to see the drawing again," 
0180 PRINT "and <f1> to get back to the text." 

0190 PRINT | 

0200 INPUT “Joystick in port nos (1 or 2) :"s portno 
0210 IF portno<i OR portno>2 THEN portno: #2 


0230 USE turtle 

0240 USE joysticks 
0250 graphicscreen (1) 
0260 background (1) 
0270 pencolor (3) 


0290 LOOP 

0300 joystick (portno,direction ,button) 
0310 IF direction THEN 

0320 setheading ((direction-1) #45) 
O330 forward (1) 

0340 ENDIF 

0350 IF button THEN // change color 
0360 pencolor ((inq(6)+1) MOD 16) 
0370 ENDIF 

O380 ENDLOOP 


LiGHT PEN 


In order to understand how a light pen works, you have to 
know something about how the picture on your TV or monitor 
screen 15S formed. The picture 1s created by an electron 
beam which scans back and forth across the face of the 
screen at high speed. As it scans, the intensity of the 
beam changes. FPhosphors on the inside surface of the screen 
react to the electron beam by emitting light, thus creating 
a visible image. The picture on the screen is updated 50 or 
60 times each second, so the eye doesn’t notice this 
process. A light pen contains a photodiode in its tip. It 
can detect variations in the light level striking it. 


When the electron beam passes the point on the screen where 
the iight pen is positioned, it can be illuminated. If it 
is illuminated and a signal is sent to the computer, the 
instant when the signal arrives corresponds to a particular 
position on the screen. 


The light pen should always be conrected to control port 1. 
Next make the package lightpen accessible with the order: 


USE lightpen 


The light pen works best when the screen border is dark and 
the background is light. 


If the program segment listed below does not work right 
away, then try adjusting the contrast and intensity 
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adjustments on your display. 


Using this program you can experiment with the operation of 
the light pen. Type in the program and try it: 


0010 PAGE 

0020 USE lightpen 

0030 USE system 

0040 textcolors(0,14,6) 

0050 

0060 offset (0,0) 

0070 REPEAT readpen(x,y,ok) UNTIL ok 
0080 

0090 PRINT xy 


The program contains 2 procedures from the light pen 
package: Line 60 specifies that the light pen’s measurement 
of the coordinates of a point should not yet be offset. 

Line 70 detects where on the screen the light pen is 
pointed. 


Move the pen slowly from the dark edge in the lower left and 
corner into the light area. The program will then print out 
the light pen’s measurement of the coordinates of this 
point. Try a few times until the coordinates have been 
determined with reasonable accuracy. These coordinates are 
referred to as the light pen’s offset from (0,0). We will 
term this coordinate pair (<xoff?>,yoff?). The coordinates 
(<xoOff>,<yoff>) can vary from display to display due to 
delays in the electonic detection process. 


In line 60 of the program the offset was set equal to 
(0,0). Now change this to the values of (:xoff>,<yoff>) 
which you have just found... 


When you run the altered program and move the light pen in 
and out of the corner, it should now register the 
coordinates (0,Q). If 1t does not, you have an idea of the 
uncertainty with which the light pen can determine screen 
coordinates. Try refining your calibration. 


Now examine the coordinate range which the light pen can 
measure. It should extend from (9,0) to about (219,199). 
After this initial adjustment, we are ready to tackle some 
more challenging tasks. 


The first example takes advantage of the fact that the 
computer automatically sets some important initial parameter 
values whenever the order USE lightpen is invoked. This 

is true, for example, of the time for which the pen must be 
held at the same spot on the screen before its position will 
be registered (the procedure delay). This is also the 

case for the time which must pass from the moment when one 
set of coordinates has been found to the time when a new 
determination will begin (the procedure timeon). A 

program which is to be used to make drawings on the screen 
must be able to determine the coordinates of points very 
quickly, so delay and timeon should be set to small 

values. If accuracy is more important than speed, then 
larger values should be used. 
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The program might look like this: 


0010 PAGE 

0020 USE lightpen 
OO3O0 USE graphics 
0040 graphicscreen (0) 
0050 border (0) 

0060 background (14) 
0070 pencolor (6) 


0090 xoff22523 yoffs=-31 // use your own values 
0100 offset (xoff,yoff) 


0120 delay(1) 
0130 timeon (1) 


0150 REPEAT readpen(x,y,ok) UNTIL ok 
0160 moveto (x,y) 

0170 LOOP 

0190 REPEAT readpen(x,y,ok) UNTIL ok 
0230 drawto(x,y) 

0250 ENDLOOP 


Try changing the values in lines 120 and 130. What effect 
does this have? 


Note that all lines are connected. What should be done so 
that the pen can be lifted and lines not connected? 


If one wishes to determine the location of the pen on the 
text screen, the pen’s:coordinates must be transformed to a 
character position (<line>,<column>). The text screen has 
2o lines each with 40 columns. 


In the following example two user-defined COMAL-functions 
(FUNC line(y) and FUNC column(x)) are used to make the 
conversion. In order for the functions to operate properly, 
the light pen coordinates must have been corrected using the 
offset procedure described earlier, so that the lower left 
corner corresponds to (0,0). 


The program illustrates how a light pen can be used to make 
selections from a menu containing charcters, words or other 
choices. In this case the problem is to select words from 
the list at the end of the program and make them into a 
sentence with a maximum of 40 characters: 


0010 PAGE 

0020 DIM text#$(25,4) OF 10 

OO3SO DIM names OF 10, all¢ OF 40 
0040 ZONE 10 

0050 1:8 


0070 USE system 
0080 textcolors(0,14,6) 


0100 arrange ‘words 


0120 USE lightpen 
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O130 delay (60) 

0140 timeon (60) 

0150 accuracy (10,2) 

0160 xoff:23523; yoffie-51 // use your own values 
0170 offset (xoff,yoff > 
0180 

0190 choose ‘words 

0200 

0210 

0220 PROC arrange ‘words 
0230 CURSOR 1,1 

0240 FOR is:#1 TO 3 DO 
0250 FOR j:*i TO 3 DO 
0260 READ text$(i, Jj) 
0270 PRINT text$(i,Jj), 
0280 ENDFOR j 

0290 PRINT 

O300 ENDFOR i 

0310 text$(6,1):2"end" 
O320 PRINT text$(6,1) 
O330O PRINT AT 6,1: "Point to words with the light pen." 
0340 ENDPROC arrange ‘words 


0360 PROC choose’ words 

0370 REPEAT 

0380 REPEAT readpen(x,y,ok) UNTIL ok 
0390 IF y<199-(1-1)#8 THEN // from line 1 
0400 name$:=text$ (line (y)—-1+1,column(x) DIV 10+1) 
0410 IF name$<>"end" THEN all$:+" “+names 
0420 PRINT AT 2,1: alls 

0430 ENDIF 

0440 WHILE penon DO NULL 

0450 UNTIL name$="end" 

0460 CURSOR 20,1 

0470 ENDPROC choose ‘words 

0480 

0490 FUNC line(y) 

0500 RETURN (200-y) DIV 8+1 

03510 ENDFUNC line 

0520 

OS30 FUNC column (x) 

0340 RETURN x DIV 6+1 

0550 ENDFUNC column 

0360 

0370 DATA "Peter", "takes", "enough" 

O580 DATA "the cat", "eats", "from" 

0390 DATA "the food", "rains", “always” 

0600 DATA "everything", "remembers", "never" 
0610 DATA "the book", "forgets", "soon" 


In line 150 the procedure accuracy from the light pen 
package is used. The procedure accuracy (<dx>,<dy>) 
determines the resolution in the x- and y-directions. 


Add some additional DATA statements yourself. 
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OVERVIEW OF THE LIGHT PEN PACKAGE 


The package contains 5 procedures and a function: 





offset (<xoff>,<yoff >) 
penon 

readpen (<x>,<y>,<ok>) 
timeon (<time>) 

delay (<time>) 
accuracy (<dx>,<dy>) 


of fset (<xoff>,<yoff >) 


is a procedure which is used to offset the light pen 
coordinate pair so that it agrees with the corrdinates 
of the graphics screen. This offset can vary from 
display to display. Try starting with values such as: 
<xoff> = 75 and <yoff> =—45. 


Example: 
offset (52,-51) Light pen coordinates are offset 
so (0,0) is in the lower left—hand 
corner. 
penon 


is a function which has the value TRUE (#1) if the 
pen is touching the screen. Otherwise penon equals 
FALSE (20). 


readpen (<x>,<y>,<oak>) 


is a procedure which reads the coordinates of the 
screen position and delivers them in the variables 
<x> and <y>. The variable <ok> has the value 

TRUE if the pen is touching the screen (just as the 
function penon). 


Examples: 


REPEAT readpen(x,y,ok) UNTIL ok Read the screen 
coordinates when the 
PRINT x,y light pen is touch-— 
ing the screen. 
Print the coordinates 
on the next line. 


delay (<timea>) 


is a procedure which is used to specify the time for 
which the light pen must be held still on the screen 
before the light pen reading will be recorded. The 
light pen must be held still within the limits 
specified in the procedure accuracy. 


The parameter <time> is given in 1/60 of a second. 
Starting value: <time>=10 (i.e. 10/60 = 1/6 second) 
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timeon (<time>) 


1s a procedure which is used to specify the time 
which must pass from one screen reading until the next 
1s possible. | 


<time> is given in 1/60 of a second. Starting value: 
<time>s=30 (i.e. 30/60 = 1/2 second) 


accuracy (<dx>,<dy>) 


is a procedure which is used to indicate the size of 
the region on the screen within which the light pen 
must remain to be considered to be ‘at rest’. The 
smaller these values, the more precisely the light pen 
must be positioned to obtain a reading. 


Initial values: <dx>=4 and <dy>=2 
Examples 
accuracy (10,8) The pen is considered to be at 


rest if it is held within a 10x& 
pixel region. 
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THE SYSTEM PACKAGE 
USE system 


This package contains, among other things, procedures which 
can be used to specify how the screen display, keyboard and 
printer interfaces should operate. In addtion the package 
contains functions which provide information about your 
system, the display and the keyboard: 


textcolors (<border >,<background>,<text>) 
keywords ‘in’upper ‘case (TRUE or FALSE) 
names ‘in’upper ‘case (TRUE or FALSE) 
quote ‘mode (TRUE or FALSE) 

inkey$ 

settime (<time ‘of ‘day$>) 

gettimes 

getscreen (<screen$s>) 

setscreen (<screen$s>) 

hardcopy (<unit#>) 

currow and curcol 

bell (<duration>) 

free 

def key (<no>,<text$>) 

showkeys 

serial (TRUE or FALSE) 

setprinter (<attributes#>) 
setrecorddel ay (<duration>) 

setpage (<integer >) 


textcolors (<border >,<background>,<text>) 


is a procedure which is used to define the color 
combination of the border, background and text. On 
start-up textcolors(14,6,14) is executed 
automatically on a Commodore 64. On an SX-64 
textcolors(3,1,6) is the default value. 


Examples: 

textcolors(0,2,1) black border, red background 
and subsequent white text 

textcolors(12,11,15) grey tones 

textcolors(-1,5,-1) Only the background is 
changed (in this case to 
green). 


keywords 'in’upper ‘case(TRUE or FALSE) 


is a procedure which determines whether keywords are to 
be written in upper case (TRUE) or lower case (FALSE). 
The default is TRUE. 
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Examples 
keywords ‘in ‘upper ‘case (FALSE) Keywords are 
displayed ina 


listing with small 
letters. 


names ‘in’upper ‘case(TRUE or FALSE) 


1S a procedure which determines whether names are to be 
written in upper case (TRUE) or not (FALSE). The 
default iss FALSE. 


Example: 


names ‘in ‘upper ‘case (TRUE) Names will be displayed 
with large letters. 


quote ‘mode (TRUE or FALSE) 
15S a procedure which determines whether control codes 
and other invisible ASCII characters in string 
constants are to be displayed in reverse text (TRUE) or 


with their ASCII values enclosed in quctes (FALSE). 
After start-up the default is FALSE. 


Examples: 


PRINT statement after quote’ mode (TRUE): 
PRINT "GHello!" 


after quote ‘mode (FALSE): 
PRINT ""“2"Hello!" 


inkey$ 
is a function which reads in characters from the 
keyboard. The function inkey$ works like KEYS. 
However inkey$ awaits a character with the cursor 
flashing at its current position. 
Examples: 
answer $: =inkey$ 
PRINT inkey$ 

settime (<time ‘of ‘day$>) 
is a procedure which is used to set the clock in the 
computer (CIA#1 real time clock). On start-up the 
clock is zeroed by settime("00:00:00.0"). 


The format of the time‘of ’day$ string is: 
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hhsmmsss.t hh is the hour (O -— 24) 

or mm is the minute (0 —- 59) 

hh: mms ss ss is the second (0 - 539) 

or t is tenths of a second (O - 9) 
hhsmm 

or if a number field is left out, 

hh it will be assigned the value OQ. 
Examples: 


settime ("07:30:15") 

settime ("10:20") 

settime("0") The clock is reset to O. 
gettimes 


is a function which returns the time’of’day in the 
format hHhemm:ss.t 


Exampless 
PRINT gettimes answer e.g.: 97:22:50.4 
digital clock: 
PAGE 
USE system 
LOOP 
PRINT AT 1,30: gettime$, 
ENDLOOP 


getscreen (<screen$>) 


is a procedure which takes a copy of the current text 
screen, and saves it as the string screens. The 
string screen takes up 1505 characters. This is 
reserved by using the order DIM screens OF 1505. 


The content of the string screen$(1: 1505): 


screens (1) border color 


2 baggr. color 

> cursor color 

4 cursors line —- i 

va cursors: column - 1 
6:1505 text and color 


information 


Text and color information consists of SOO sequences of 
2 bytes each: 


character 1 For every two characters 
character 2 their color is stored. 
Ls : ae Each color takes 4 bits 
color making a byte. 


See the program examples following setscreen (<screen$>). 
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setscreen (<screen$>) 


is a procedure which creates a picture on the text 
screen. Ficture informationen is contained in the 
string screens. The string must contain at least 
1505 characters. See getscreen (<screen$>). 


Program example 1: 


DIM at of 1505, bs of 1508 
USE system 


getscreen (as) 
getscreen (bs) 
aS: =a% (12725) +b$ (726: 1505) 


setscreen (a$) 
Note: 


At two selected times during the execution of the 
program, the contents of the text screens are saved in 
the strings a$ and b# respectively. Later a string 

1s created by combining the first 725 characters of 

af (i.e. color and cursor information, and the first 
12 lines of the a$ screen image) and of b$’s last 

780 characters (i.e. the bS$ screen’s lower 12 lines). 
The combined image is finally presented on the screen. 


Program example 2: 


PROC help CLOSED 

DIM #1% OF 15035,s2$ OF 1505 

USE system 

getscreen(si#) // save screen image 

OPEN FILE 10, "skm.help",READ 

READ FILE 10:s2$% 

CLOSE FILE 10 

setscreen(s2$) // shows a user help screen 

WHILE KEYS=CHRS$(0O) DO NULL 

setscreen(si$) // the old image back again 
ENDPROC help 


hardcopy (<unit$>) 


is a procedure which prints out the contents of the 
text screen to the unit which is given in the string 
unit$. The printout begins with a carriage return. 


Examples 


hardcopy ("lpi") The contents of the text screen 
is printed on a lineprinter. The 
order has the same effect as 
<CTRL-P>. 
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currow and curcol 


are two functions which return the current row and the 
current column respectively. 


Examples: 

rowr:=currows columns: =curcol 

PRINT AT O,curcol-S: names 
bell (<duration>) 


is a function which activates COMAL’s "bell". The 

parameter duration must be an integer in the range 1 

to 255. The value 1 corresponds to a real-time @ 
duration of about 0.15 seconds. On start-up an 

automatic bell(3) is executed. 


Example: 
bell (10) Sound for 1.5 sec. 


free 


is a function which returns the number of free bytes in 
working memory. A more complete overview of the use of 
working memory is obtainable using the command SIZE. 
But because SIZE iss a command, it cannot be used from a 
running program. 


Example: 
PRINT free 
defkey (<no>,<text#>) 
1S a procedure which 1s used to redefine the meaning of 
the function keys. The keys are numbered 1,..,8,11,..18. 
The numbers 1 - 8 are normally active for indication of 
the usual function keys <f1> — <*8-. But during 
program execution, the function keys will correspond to @ 
numbers i1 - 186. The string text# may consist of a 


maximum af 32 characters. 


The procedure showkeys will print out a list of the 
current definitions of the function keys. 


Examples: 
On start-up the following is performed: 


defkey(6,"LIST ") Activating <#6&> prints LIST 
on the screen. 


The <#3> and <#4> can e.g. after redefinition be used 
to assist with the writing of procedures: 


defkey(S,"AUTO"13S""13"PROC ") 
defkey (4, "ENDPROC"13""141"SCAN"13"") 
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<¥#3> will cause: AUTO 
0010 
0020 PROC 


<#4> will cause: XXXX ENDFPROC 
(Interrupt AUTO-numbering. ) 
SCAN 
(Which checks the structure of the 
procedure and allows use of the 
procedure as a command.) 


Program example: 


USE system 

defkey(15,"COMAL for everyone! "13"") 
INPUT “What did you say? “: text? 
PRINT text? 


If the <*S> key is activated in response to the INPUT 
statement, the system will-react as if the message came 
from the keyboard and print it out. 


showkeys 


1S a procedure which prints out a list of the meanings 
of the function keys. 


serial (TRUE or FALSE) 


1S a procedure which controls whether communication 1s 
sent to the serial port or to the IEEE-488 module (‘if 
avallable). 


Examples: 
serial (TRUE) Send to the serial port. 
serial (FALSE) Send to the IEEE-488 module. 


setprinter (<attributes$>) 


1S a procedure which is used to select the unit number 
and attributes of the peripheral printer. Printout to 
the lineprinter (lps) will thereafter be performed 
according to the rules given by the attributes. These 
are given in a string during procedure calls. 


Possible printer attributes: 


f/a- donot translate from C64 ASCII to standard ASCII! 
/at convert from C64 ASCII to standard ASCII 


/i- suppress line feed after carriage return 
/i+ execute line feed after each carriage return 


/t-. ignore ‘time out’ signal and continue printout 
/t+ interrupt with error message if time runs out 
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Secondary adresses for the Commodore MPS 801 (partly 
also MPS 802) printer: (See instruction manuals for 
other printers.) 


/@*- no secondary address used 

/s0 write data as received 

/sl write data in previously defined format 

/e2 save format information 

/@3S number of lines per page 

/s4 allow explanatory error messages 

/e5 define a programmable character 

/e6& number of blank lines between each printed line 
/s7 print with lower case 


Upon start-up in COMAL “lpa" is defined as the unit 
with the attributes u4:/a-/1-/t+/s7. 


The MPS 801 printer can be set to act as unit 4 or unit 
= by means of a switch on the back panel. 


Examples: 

setprinter ("u5380") "los" means hereafter 
unit Ss printout with 
upper case. 

setprinter ("lp:/at+/l1—-") Convert to ASCII, send 


no line feed. 


A procedure to define the number of lines per page on 
the MFS 802 printer: 


PROC page ’802(lines‘pr’page) CLOSED 
OPEN FILE 1,"“lp:/s3",WRITE 
OPEN FILE 2,"lp:", WRITE 
PRINT FILE 1: CHR$#(lines ‘pr ‘page), 
PRINT FILE 2: CHR$(147), 
CLOSE 

ENDPROC page ’802 


setrecorddelay(<duration>) 


is a. procedure which causes COMAL to pause under writes 
to a random file. The parameter <duration?> is given in 
milliseconds. The disk operating system needs time to 
write a block to the diskette before the COMAL system 
can send a new positioning order. It is rarely 

. necessary to use the procedure. When COMAL is 
initiated, an. automatic setrecorddelay(50) is carried 
out, unless the IEEE module is connected with the COMAL 
cartridge. In that case a setrecorddelay(0O) will be 
executed. 


setpage (<integer >) 


is a procedure which determines to which overlay the 
orders PEEK and POKE will refer. See Chapter 8 for 
more information on this. The utilities program 
showlibs on the demo diskette (or tape) uses this 
procedure. 
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THE FONT PACKAGE 

The package font contains & procedures which are used to 
define new screen characters. It is possible to change an 
entire character set or just an individual character. 

The package is activated with the order 


USE font 


The package affects the 4 character sets numbered: 


O: User-defined read/write 
1s: User-defined read/write 
2: Upper case/graphics set read only 
3: Upper/lower case letters read only 
The Commodore 64 uses a double character set. Normally 


COMAL uses character set 3. By activating <SHIFT C=? you 
can switch back and forth between character sets 2 and 2. 
These two character sets are permanently available in the 
working memory of the computer, so they cannot be changed. 


With the font-package it 1s possible to add a new double 
character set numbered © and i. This character set is 
stored in a protected area of the working memory of the 
computer. 


There are now several options: 


1. You can move a copy of the normal character set of the 
computer into the area reserved for the user character 
set and change some of the characters. 


2. You can fetch a completly new character set from 
diskette or tape and store it as the user-defined 


character set. It will go into effect at once. Of 
course it is essential to have such a character set 
prepared and available on diskette or tape. A 


character set is available on your demo diskette or 
tape. But it is also possible to create your own and 
to store it for later use. 


Remar ks: 


* The character set used corresponds to screen 
characters. Their character code are not in accord 
with the standard ASCII values. See Appendix A for 
standard screen character codes and ASCII codes. 


The following command will print out all the standard 
screen characters. Issue the order with default screen 
and cursor colors. (The screen image starts at memory 
address 1024.): 


for i#0 to 2335 poke 1024+i1,i 


* The user-defined character set is also used by the 
procedure plottext from the graphics-package. 
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* Because a printer uses its own character set, font 
will have no effect on PRINT and LIST orders directed 
to the printer. On the other hand <CTRL-D> 
(printscreen) will cause an exact copy of the 
Graphics screen image to be printed out on a MPS 8Ol 
compatible printer. 





Example of character replacement: 


First we fetch a character from the standard character set 
to see how it is stored in an 8x8 raster pattern of pixels. 
The following program can be used for this purpose. 


The character is fetched by means of the procedure 
getcharacter. The rest of the program has been added to 
provide a nice printout of the character in an 8x8 matrix. 
We let the string function bin$ convert the individual 
characters in the fetched raster pattern to binary numbers. 
These numbers are then printed under one another to create 
the bit pattern of the character: 


0010 // save "@Fetch Character" 
0020 USE font 

O0O3O DIM raster$ OF 8 
0040 PAGE 

0050 INPUT “Character set 
0060 INPUT "Character no. 
0070 PRINT 

0080 getcharacter (choice#,character#¢,raster$) 

0090 FOR i:=1 TO 8 DO 

0100 PRINT TAB(12) ,bin¢$ (ORD (raster$(i))») 

0110 ENDFOR i 

0120 

0130 FUNC bin#(number) CLOSED 

0140 DIM binnumber$ OF 8 

0150 binnumber $: ="00000000" 

0160 bits=1 

0170 FOR i#:=8 TO 1 STEP -1 DO 

0180 IF number BITAND bit THEN binnumber$(i#):="1" 
0190 bits+bit 

0200 ENDFOR i# 

0210 RETURN binnumber$ 

0220 ENDFUNC bin$ 


“ss choice¢ 
": character 


Try out the program. Choose a character from the double 
standard character set: 2 or 3. Since we have not yet 
prepared any user-defined characters, any attempt to fetch a 
character from sets 0 or 1 will result in an error message. 
The character a has the number 1 in character set number 

3. 


Next we will prepare a user-defined character by simply 
moving a copy of the standard character set up to the user- 
defined area. Since no user-defined character set has yet 
been created, the order linkfont has this effect. Write 
therefore: 


use font 
linkfont 
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This way a user-defined charater set (0 og 1) is created for 
immediate use. In addition the old screen image is hidden, 
and a new picture is created for using the new character 
set. It is always possible to return to the standard 
character set by using the order DISCARD (which preserves 
any program in working memory) or NEW (which does not). 


It 1S now possible to change the characters in the double 
character set O - li. The brief program which follows reads 
in individual charcters by means of DATA statements and 
makes them part of the new character set’ with the order 
putcharacter. 


The DATA in the program for a letter # (the Greek letter 
‘phi’). This character can replace any charcter in set O or 
oie If you wish to have this Greek letter available instead 
of the "pound" sign, you can assign it character number 28 
in character set number 1. Then when you press the 

“pound” key, a # will appear on the screen. 


Try replacing some other characters. Notice that there is 
an immediate effect on the display screen. 


0010 // save "Save Character" 

0020 USE font 

0030 DIM raster? OF 8 

0040 FOR i:=1 TO 8 DO 

0050 READ byte 

0060 raster$(i:i):=CHRS$ (byte) 

0070 ENDFOR i 

0080 PAGE 

0090 INPUT "Character set : ": choice# 
0100 INPUT "Character no. : ": no# 
0110 putcharacter (choice#,character#,raster$) 
0120 

0130 DATA %~00000000 

0140 DATA %~00000000 

0150 DATA 4700111110 

0160 DATA 2401101110 

0170 DATA 201111110 

0180 DATA 401110110 

0190 DATA 401111100 

0200 DATA %~00000000 


(NB: Remember to execute use font and linkfont 
before running this program.) 


On the demonstration diskette you will find the program 


fonteditor which can be used to aid in the definition of 
new characters. 


Replacing an entire character set 





If a double character set is available on diskette, it can 
be fetched into working memory by using the orders: 


discard (to erase earlier linkfont) 
use font 
loadfont ("<filenames>") 
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where <filename$> is the name of the diskette- or tape 
file. Thereafter the new character set and screen image can 
be used. 


The package font contains the procedures: 


linkfont 

loadfont (<filenames>>) 

savefont (<filenames$>) 

keepfont 

getcharacter (<character set>,<character>,<raster$>) 
putcharacter (<character set>,<character>,<raster$>) 


FONT PACKAGE PROCEDURES IN DEPTH: 
linkfont 


is a procedure which is used to define a new double 
Character set number O and 1. The procedure should 
only be used as a direct command, for a program cannot 
continue after a linkfont statement. 


* Room is reserved in working memory for the new 
character set and for the screen image (4000 bytes 
for the character set and 1000 bytes for the screen 
image). 


* The extra screen becomes the current screen and is 
cleared. 


* Because the variable table in the working memory is 
Ooverwritten by the new character set, all COMAL and 
package names will be undeclared. 


* If linkfont has not been called earlier, either 
directly or indirectly through loadfont, then the 
standard character set (2-3) will be copied over as 
the new character set (0-1). 


* If linkfont has been called previously, nothing 
happens. It is thus not possible to overwrite an 
existing user-defined character set with a new 
linkfont-command. The user-defined character set 
must be removed first by using the order DISCARD or 
NEW. Individual characters on the other hand can be 
replaced using the order putcharacter. 


* The double character set is treated as a part of 
your COMAL program. When the program is stored 
using the SAVE command, the user character set is 
saved along with it as a single file. When the 
program is loaded again later using the LOAD order, 
the character set is also loaded and ready to go 
(even before the program is run!). 


loadfont (<filename$>) 
1S a procedure which reads in a character set with the 


name <filenames> from diskette or cassette tape. 
First loadfont executes an automatic linkfont, 
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reserving room in working memory for the fetched 
character set and the extra screen image. 


The procedure loadfont replaces any existing user 
character set with the one which has been read in. The 
new character set and screen image can then be used as 
the current character set and screen. 


savefont (<filenames>) 


is a procedure which copies the user-defined double 
character set into the working memory and saves it on 
diskette or tape under the name <filename$>. 


keepfont 


is a procedure which is used to "freeze" a user-defined 
Character set, so that it cannot be celeted using 
DISCARD or NEW. It is necessary to turn off the 
computer to return to the standard character set. 


* loadfont still works. A newly read-in character 
set will also be "frozen". 


* After keepfont, characters wili NOT be saved 
together with a COMAL program by the command SAVE. 


getcharacter (<character set>,<character>,<raster$>) 


iS a procedure which fetches a raster image of the 
character with the screen code <character> from 
<character’set>. The image is fetched in the form of 
a string variable <raster$> which is 8 characters 
lang. 


Fermitted values: 


<character sets>: ©, 1, 2 0g 2 


<characters> : 0, 1,..., 255 
Examples: 
getcharacter (3,1,raster$) The character ais 
fetched from character 

set 3. 

DIM as OF 6 The code character D’s raster 
image 

USE font is fetched and displayed. 

getcharacter (2,4,a$) 

PRINT at 


Printout: XLFFFLX 


putcharacter (<character set>,<character>,<raster$>) 


is a procedure which prints out the character with the 
screen code <character> in <character ‘set> with the 
raster pattern in the string <raster>. 
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Allowed values: 


<character ‘set>: oO, I 
<character > Oy Lawcee Zoo 


Examples: 
putcharacter (1,5,""O""O"<FFF<"0"") 


In the extra character set {1 the character ais 
assigned screen character number §. 


=213- 
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COMAL Files 


WHAT IS A FILE? 


As you begin to use your 
computer to do more and more 
jobs for you, it will be very 
convenient to be able to create 
files for storing information. 
You may wish to save business 
transactions, financial records, 
address lists, the results of 
calculations, measurements or 
other data for later use. OF 
course it is possible to 
purchase commercially produced 
"database" software to help you 
do this. Nevertheless many 
computer owners elect to write 
their own programs, so that thev 
can tailor them precisely to 
their particular needs. 





A file is a collection of data, organized for storage and 
retrieval. The storage medium can be a Datassette tape 
or a diskette. Because serious file handling usually 
requires the use of a disk drive, this chapter will 
concentrate mostly on file storage with a disk drive. 


There are several ways in which files can be organized. 
Sometimes it 1s convenient to save a set of information one 
item after the other ina sequential file. Sequential 
¢#iles are easy to use and do not require a qreat deal of 
prior planning with respect to the number of storage units 
each item will require. On the other hand when sequential 
files are used it 1s necessary to read the entire file into 
the computer 's memory. And you must re-save the entire file 
again each time you have finished working with it. Storing 
data as sequential files is useful as long as the file does 
not get too large. 


There 1s a way to get around the problem of having to handle 
the entire file all at once. Random-access files can be 
created, so you only need to read in a small portion of the 
file when you want to change it or refer to it. In this case 
you must plan ahead carefully, allotting an appropriate 
amount of space for each "set" of data (i.e. each record). 
If we know how much room each record takes up, it 1s pos- 
sible to fetch or save a single record at a time. Thus the 
use of random-—access files can speed up access to some types 
of information on a diskette (they cannot be used with a 
Datassette tape unit). Random-access files are appropriate 
to use for handling large collections of systematic data. 


In this chapter we intend to cover several important uses 
for COMAL files: 
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saving and loading programs and procedures 


an address list filing program using sequential files 


a random-access inventory file program 
moving files between diskettes 


x * kK 


The demonstration programs described in this chapter are 
found on the demo diskette (or tape) distributed with the 
COMAL cartridge. In addition, complete program listings are 
avallable in Appendix H. 


SAVING PROGRAMS AND PROCEDURES 


As you proceed to write more programs, you will find that 
they become larger. But you will also find that many of the 
operations to be carried out are the same: saving data, 
fetching data, printing tables, printing a title screen, 
entering a user response from the keyboard, etc. It will 
become very natural for you to do these jobs and others 
which may be required again by using COMAL procedures. 

Later on the same procedures can be used with little or no 
changes. 


There are a number of COMAL disk drive operations which make 
the building of new programs from available procedures 
particularly easy and convenient to do. An overview of 
these operations is shown in the table which follows. 


Pa COMPLETE FPROGRAMS PROGRAM SEGMENTS 


SAVE “file name>" 








LIST<segment?"<file name>" 









LIST "sfile name>" 










STORAGE: 
SAVE "testfile" LIST 1000-1095 "printout" 
LIST "testfile" LIST printout "“printout.i" 


LOAD "<file name>" MERGE<lines>"<file name>" 
ENTER "file name>" ENTER "<file name>" 
RETRIEVAL: 
1LOAD “testfile" MERGE "printout" 
ENTER “testfile" MERGE 1100 "printout" 
MERGE 1100.5 "printout" 
ENTER “printout” 


em ce we cw ce cree ee cm we en cw cs ee we a ee we ce we ew ee ew a we we ow oe = ee ee 


It should also be mentioned here that the DISPLAY 
command can be used to save entire programs, 
individual procedures or sequences of line numbers 
to diskette (or tape). The order DISPLAY 10-100 
“sample" saves program lines 10-100 with no line 
numbers as an ordinary sequential file. The file 
can (only) be retrieved using an INPUT FILE order 
or the GETS order. Other formats, analogous to 
the formats of the LIST command, are also 
permitted. The DISPLAY command can be used to 
create a sequential file from a COMAL program. 
The file might then be loaded into a text editor 
(e.qg. EASYSCRIPT). 


cr me ce ec a we ee we ce es wc we we we ce ww ww cs ew ee ee ee owe ee rw 
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Let ’s quickly review the storage and retrieval of COMPLETE 
PROGRAMS. Consider the lefthand column of the table. 


The commands SAVE and LOAD are already familiar to you. You 
can use SAVE to transfer a copy of your COMAL program file 
currently in memory to diskette. The syntax is SAVE "<file 
name>", where the item <file name> is a program name (up 

to 16 characters) of your choice. Beginning a file name 
with @ has a special meaning: The file will be deleted if 
it exists, and the new file will be saved in its place under 
the same file name. 


The order LOAD is the reverse operation of SAVE. The LOAD 
order has the format LOAD "<file name>" and causes the 
program file <file name> to be copied from the diskette to 
the COMAL program storage memory of vour Commodore 64. When 
you LOAD a program file, the previous contents of the COMAL 
program area will be erased. Note that only a program file 
(denoted by prg in the directory?) can be LOADed. A 

complete program can also be LISTed to a diskette where it 
will be stored as a sequential file. It must then be 
ENTERed or MERGEd to be retrieved later 


The commands RUN and CHAIN can also be used to bring program 
files into memory from the disk drive. See the more 
detailed description af these orders in Chapter 4. In 
addition a closed procedure, saved using SAVE, can be 
fetched as an external procedure during program execution 
(see the descriptions of EXTERNAL and FROC in Chapter 4>. 


Now let’s take a look at the column titled PROGRAM SEGMENTS. 
This information can be a real time-saver, so study it 
carefully! 


Suppose that you have developed an ingenious procedure 
called quick’save for quickly storing a list of items and 
prices on diskette. The procedure 1s so general, that it 
could be useful in many other programs. If it is more than 
a few lines in length, it will not be convenient to type it 
in each time it is to be used. It should be LIiSTed to 
diskette by using the order LIST quick’save 

“prc.quick’ save". If you do this and type dir. you will 
observe that the file prc.quick’Save is stored as a 
sequential (not a program) file on the diskette. Note that 
it cannot be LOADed like a program file; to get it into 
program memory you must use either MERGE or ENTER. These 
orders will be described shortly. 


You are also permitted to save your procedure by 
referencing the line numbers for the procedure. 
For example you could store quick ‘save by 
writing: list 1000-1090 "prc.quick save". 
Typing dir will verify that the procedure has 
been saved as a sequential file. The procedure 
can now be brought into another program using the 
MERGE or ENTER orders. 


ee re ee ome ce ce ce ee ee ee we we ee ee we ee a ww ee ww ee wee ee 
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Now comes the good part. When you want to use the procedure 
again, you have the following alternatives: 


* Write merge "prc.quick’save". Your procedure will be 
copied from the disk drive and appended to the program in 
memory. It will appear with line numbers starting 10 
beyond the last line number in the program, even though 
the original file was LISTed with line numbering 1000- 
1090 


* You may instead choose to write merge 1100 
“prc.quick ‘save". In this case the procedure will 
appear in your current program from lines 1100 and beyond 
with a line number interval of 10 (the default value). 
If you want the procedure to start at line 1100 with an 
interval of 5 between lines, just write merge 1100,5 e 
“prc.quick’save". 


WARNING: Be careful when merging a procedure in 
the middle of a program. You must be sure that 
there is room enough for the procedure with the C= ~ 


line number interval selected. Otherwise the > 
procedure will get mixed up with other —— 
instructions or erase them if line numbers 

coincide. 


* In case you have LIiSTed an entire program to 
diskette, you may want to use the order ENTER. If 
you write enter “printout” for example, the 
sequential file printout will be read into the 
active program area. (NOTE: Any other program in 
memory will be deleted.) 


If you have worked with other programming languages and 
operating systems, you will appreciate how convenient 
these facilities can be while developing programs. 


SEQUENTIAL FILES - AN ADDRESS LIST 


In Chapter 3, program 19, we saw a simple example @ 
illustrating how to save numbers on a sequential file. You 

may recall that a sequential file must be opened before data 

is saved or fetched. After use the file must be closed. 


The formal structures for these operations are as follows: 


Qpen a file, save data, close the file. 
OPEN FILE <fileno>,<filenamet>, WRITE 


PRINT FILE <fileno>: <data element> 


CLOSE FILE <fileno> 


Open a file, fetch data, close the file. 


Chapter 6 - -223- COMAL FILES 


OPEN FILE <fileno?>,<filename#>,READ 


INFUT FILE <fileno>: xvariable name> 


CLOSE FILE <fileno> 


We will now turn our attention to a practical problem. 
Suppose you want to create a program to save names, 
addresses and telephone numbers. The following example 
illustrates the kind of data we want to Save and variable 
names which we will use: 


example string variable 
John Smith name$ () 

1200 Wilson Drive street$() 
Anytown, PA 19380 towns () 

(212) 123-4567 phones () 


Notice that all four string variables are to be defined as 
arrays. We intend to design the program to handle up to 100 
names with addresses and phone numbers. We will refer to 
the collection of information illustrated above a data 
record and each of the individual variables which consti- 
tute the record as a data element. In this example each 
data record will consist of four eiements. 


Note that all four string variables must be declared as one 
dimensional arrays. We plan to permit our program to handie 
up to 100 records. Consider some of the tasks which this 
program will have to handle: 


LOAD all the records in the data file intc memorv 
CREATE a data record with name, address and phone number 
LIST all records in the fiie 

SEARCH through the tile to find certain records 

SORT the file alphabetically bv name 

CHANGE a record 

DELETE a record 

SAVE the file on diskette 


* eK KK OK Kk 


Of course there are other operations one might want to 
perform on a file, but we will limit this example to the 
above operations in the interest of simplicity. When you 
have understood the procedures described in this section, 
you will be able to extend or revise this program so that it 
best suits your needs. Those of you who received this book 
with the COMAL cartridge will find this program on the demo 
diskette or tape under the file name Addr List Demo. The 
program listing is also given in Appendix H. 


We intend to take a careful look at this program. Flease 
note that it has not been “optimized". It has been written 
as simply and clearly as possible to make it easy to 
understand. As you learn more and more about sequential 
files, feel free to make modifications and improvements'! 


The program starts out with a line indicating the name of 
the files 
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0010 // SAVE "@Addr List Demo 


Notice that we have used a remark statement (//) and 
included SAVE " ahead of the file name. This little trick 
makes it easier for you to save modifications of your 
program as you develop it and revise it. Just move the 
cursor to this line, remove the first part of the line by 
typing blanks (or use <INST/DEL>). When you press <RETURN>?, 
the new version will be saved. The @ symbol included as 
the first character of the file name causes the existing 
program file to be deleted before the new file is saved. 


WARNING: Be careful when using this method: you 
could lose a program file. Be sure you have a 
backup copy of your program and update it from 
time to time. Do not make revisions using the 
demonstration diskette or tape. load the program, 
then save later revisions to another storage disk 
or tape. 





The next lines in the program listing take care of 
DIMensioning of arrays and string variables used in the 
program: 


0020 DIM replys OF 1, name$(100) OF 40 

0030 DIM street$(100) OF 40, city#(100) OF 40 
0040 DIM phone$(100) OF 20, flags OF 40 

0050 DIM searchkey$ OF 40, string OF 150 
0060 number:=0 // number of records 


Notice here that we have made provision for the storage of 

100 data records each consisting of four elements: a name, 

street, town and phone number. Each of these elements may 

be up to 40 characters long. This choice means that the 

sequential file can take up to 4x40x100 or about 16 

kilobytes in memory. Since a total of about 30 KB is 

available, and the program only takes up about 4 KB, more 

room 1S available. You can change these numbers, if you & 
wish. 


Next comes an introductory screen describing the program: 


0070 PAGE 

0080 PRINT "This program illustrates the use of" 
0090 PRINT “SEQUENTIAL FILES. It can be used to" 
0100 PRINT “create a list of names, addresses" 
0110 PRINT “and telephonenumbers. " 
0120 PRINT "Each record will have the formats " 
0130 PRINT 

0140 PRINT " name" 

01350 PRINT "“ street" 
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0160 PRINT “ city" 

0170 PRINT “ phonenumber " 

0180 PRINT 

0190 PRINT 

0200 PRINT "Press any key to continue..." 
0210 

0220 wait ’for ‘keystroke 

0230 


The statement PAGE clears the screen and the following lines 
simply print information on the screeen. Notice the 
procedure wait ’for’keystroke. This is a procedure which 

you might find convenient to use in your own programs: 


2240 PROC wait ‘for ‘keystroke 
2200 PRINT 

2260 PRINT "< >..."3 

2270 REPEAT 

2280 reply$:=KEY$ 

2290 UNTIL repl y$< >CHR$ (0) 
23500 PRINT AT 0,2: replys 
2310 ENDPROC wait ’for ‘keystroke 


You may or may not want < >... to be printed on the screen 
whenever the computer 1S awaiting an operator response. 
Change it or delete it as you wish. The REPEAT...UNTIL loop 
will be executed continuously as long as no key is 
depressed, since the value of the COMAL function KEY# remain 
equal to CHR#(0O). When a key is pressed, KEY takes on the 
value of the character sent from the keyboard, and reply$ 
will no longer be equal to CHR#(0). The REFEAT...UNTIL loop 
will be terminated, and execution proceeds to the next line. 
The PRINT AT 0,2: reply# statement causes the character 
which was sent from the keyboard to appear inside the 
brackets in the < >... symbol. 


Now take a look at the main program loap: 


0240 LOOP 

0250 show ‘menu 

0260 flag$:="" 

0270 wait’ for ‘keystroke 
0280 CASE replys OF 
0290 WHEN "i" 


0300 load ’file 
0310 WHEN “2" 

0320 create record 
0330 #£=WHEN "3" 

0340 list ‘file 
03350 WHEN “4" 

0360 search'‘file 


0370 WHEN "5S" 
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0380 sort ‘file 
0390 WHEN "6" 
0400 change ‘record 
0410 WHEN "7" 
0420 delete ‘record 
0430 WHEN "8" 
0440 save file 
0450 OTHERWISE 
0460 PRINT "Illegal reply..." 
0470 wait for ‘keystroke 
0480 ENDCASE 
0490 ENDLOOP 
This is really the heart of the program. The first 


subprocedure encountered displays the program menu: 


0500 
0510 


0690 
0700 


The procedure clears the screen, 


avallable, 


string variable flag$, 
inform the user about various conditions, 
to Please load or create file... 


in memory. 


Considering again the main program loop, 
variable flag# is again set equal 
empty string, 


executed. 


digit from 1 to 8), 
If the choice is not a valid one, 


PROC show ‘menu 
PAGE 
PRINT “----- waa== MAIN MENU ===2=-----—- " 
PRINT 
PRINT 
PRINT " <1> LOAD the file" 
PRINT " <2> CREATE a record" 
PRINT " <3> LIST the file" 
PRINT “ <4> SEARCH the file" 
PRINT " <3> SORT alphabetically" 
PRINT " <6> CHANGE a record" 
PRINT " <7> DELETE a record" 
PRINT " <B> SAVE revised file" 
PRINT 
PRINT 
PRINT “Records: "snumber 


FILES 


IF number=0 THEN flag$:="Please load or create file...” 


PRINT 
PRINT flags 
ENDPROC show ’menu 


indicates the user choices 
and shows the number of records in the file. 


which 1s used in the program to 


if there are no records 
This message will be printed below the menu to 
gQuide the user. 


(in line 260) 
so it can be used later for other purposes. 
In the next line the procedure wait ’for ‘keystroke is 


we see that the 
to the 


When a valid user choice has been entered (a 


out the message Illegal reply... 


any key. 


The 


will be set equal 


the program will branch as appropriate . 
the program simply prints. 


and waits for you to press 


We will now consider each of the eight available file 


handling functions. 


selecting 


1 from the menu, 


The first user choice, 
is LOAD the file: 


activated by 
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0710 

0720 PROC load‘file 

0730 OPEN FILE 1,"Addresses" ,READ 
0740 INPUT FILE 1: number 

07350 FOR no:#1 TO number DO 


0760 INPUT FILE 1: names (no) 
0770 INPUT FILE 1: street$(no) 
0780 INPUT FILE i: city#(no) 
0790 INPUT FILE 1: phone$(no) 


0800 ENDFOR no 

0810 CLOSE FILE 1 
0820 ENDPROC load’file 
Osso 


Of course this procedure can only be used after a file has 
been created and is available on the diskette in the disk 
drive. Usually this will be first choice a user makes after 
starting the program. It is important to understand the 
procedure load‘file, for it shows you how to read a 
sequential file from a diskette into program memory. The 
first thing done in this procedure is to OFEN FILE number 
1 as a READ file called Addresses. Should you want to 
call the file some other name, you can simply alter this 
file name to one of your choice, here and elsewhere in the 
program. The easiest way to do this is by means of the 
CHANGE order (change "Addresses","your choice"). 


We have decided to let the first element in the file be 

called number corresponding to the number of records in 

the file. This variable was the first one to be saved, and 
it 1s the first one to be read in now. Now that the number 
of records in the file is known, the file itself can be read 
in using a simple FOR...ENDFOR loop. (In Chapter = we used 
the logical function EOF (<fileno>) to announce End Of File?. 


Notice the use of the INFUT FILE statement to define the 
elements in the arrays name$(), street$(), towns() and 
phone$(). Finally, notice that file 1 must be CLOSEd 
after the data input is completed. 


The following procedure, activated by user choice 2, can 
be used to create new records for the file: 


0840 PROC create‘record 

0850 PAGE 

0860 PRINT "se2s2 CREATE A NEW RECORD esess” 
0870 PRINT 


0880 PRINT Da «a 
0890 IF number#100 THEN flag$:="No more room for data!" 
0900 IF flag$="" THEN 


ae — 


0910 Mumberit+il Ae ie ete Se GF 
0920 INPUT “Name ": names (number ) 
o930 INPUT "Street “s: streets (number ) 
0940 INPUT “City "s city$ (number ) 
09350 INPUT "Phone "“: phones (number ) 


0960 ENDIF 
0970 ENDPROC create ’record 
0980 


The procedure begins by clearing the screen and indicating to the 
user what is happening. If there 1s no more room for data 
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(because number # 100), then the message variable flag is 

set to No more room for data!, and the next lines will not be 
executed (the condition flag#=z""_ will not be fulfilled). If 
there are fewer than 100 records, then the number of records 
counter number will be updated (numbers:+1 in line 910), and 

the user can input the four data elements. Execution returns to 
the main program loop. 


User choice 3 allows entire contents of the file to be listed: 


0990 PROC list ’file 

1000 PAGE 

1010 PRINT “sssz2s LISTING THE FILE sesses" 
1020 PRINT 


1030 IF number#0O THEN 

1040 flag$:="No files in memory!" aad 
10350 PRINT 

1060 ELSE 

1070 FOR noz:#1 TO number DO print ‘record (no) 

1080 ENDIF ‘ 

1090 ENDPROC list ’file 

1100 


The screen is cleared and a user message is displayed. If there 
is no file in memory (number=0), then a message is sent back to 
the menu display by means of flag$. If there 1s a file in 
memory, then it is listed by the FOR...ENDFOR loop. Notice that 
a wait occurs as each record iss displayed. Simply holding down 
any key will make the records scroll up the screen. 


The search option is activated by user choice 4 from the 
main menu. When a file is available in memory, it can be 
searched find a name, street, town or other information: 


1110 PROC search ’file 

1120 PAGE : 

1130 PRINT "sssss FILE SEARCH esss:s"“ 
1140 PRINT 

1150 PRINT 

1160 flag$:="I am searching...” 

1170 INPUT "Search key: ": searchkey$ 


1180 FOR nos#1 TO number DO 
1190 string$: =name$ (no) +street$ (no) +city$ (no) +phones (n 
1200 IF searchkey# IN strings THEN print ‘record (no) 


1210 ENDFOR no 
1220 flags:="" 
1230 ENDPROC search ’file 


After clearing the screen and informing the user, this 
procedure allows a search key to be entered. This can be 
any string of characters at all, however capitalization must 
be the same as in the record element which is to be searched 
for. The COMAL statement IF <condition> THEN <procedure> 

is most useful here. Each record is checked by means of the 
FOR...ENDFOR loop. If any record contains the search key, 
then the entire record will be printed by the subprocedure 
print ‘record (nr): 
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1250 PROC print ‘record (no) 

1260 PRINT 

1270 PRINT AT 0,108 “eewe cere r ere (“,no,")>" 
1280 PRINT AT 0,10: names (no) 

1290 PRINT AT 0,10: street (no) 

1300 PRINT AT 0,10: city (no) 

1310 PRINT AT 0,10: phones (no) 

1320 PRINT 

1330 IF flag$="I am searching..." THEN wait ‘for ‘keystroke 
1340 ENDPROC print ‘record 

1350 


Notice the use of the variable flag# here. It is set 
equal to "I am searching..." (in line 1160). This signals 
the subprocedure (in line 1330) that a wait should occur 
after each record is displayed. The variable flag# is 
reset to the empty string at the end of the search 
procedure. 


Now we will examine one of the more challenging procedures 
in this program. The entire file can be sorted 
alphabetically by name. This option is activated by user 
choice §$ from the menu. Note that a prerequisite for 
proper use of this function is of course that names must be 
entered correctly, last name first, as the first element of 
each record. Of course a sort could be carried out 
according to any other element you may choose by simply 
modifying the procedure which follows as appropriate. 


1360 PROC sort ‘file 

1370 PAGE 

1380 PRINT “sss:s SORT BY NAME ALPHABETICALLY e::ss::" 
1390 PRINT 

1400 PRINT 


1410 

1420 PROC swap (REF a$,REF bs) CLOSED 
1430 c$r=ass aSr=bs; bS: =cF 

1440 ENDPROC swap 

14350 

1460 REPEAT 

1470 no ‘swaps: =TRUE 

1480 FOR noz#1 TO number-1 DO 

1490 PRINT AT 10,1: "Sorting... ",no 
1300 IF names (no+1)<names(no) THEN 
1510 swap (names (no) ,names (no+1) ) 
13520 swap (streets (no) ,street$ (not) ) 
13530 swap (city$# (no) ,city# (no+1) ) 
13540 swap (phone$ (no) , phones (no+1) ) 
1550 no ‘swap: =FALSE 

1360 ENDIF 

1370 ENDFOR no 


13580 UNTIL no’ swap 
1390 ENDPROC sort ‘file 
1600 


As in Chapter 3 Program 19, the sorting algorithm used 
here is the simple bubble sort. Compared to what we did in 
Chapter 3, we have placed the swap procedure inside the 
sort ‘file procedure. This is done to show an example of a 
local procedure inside another procedure. 
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The FOR...ENDFOR loop is carried out for each pair of names 
in the list. If the names are not in alphabetical order’ the 
names are swapped. The variable no’swap will now be equal 
to FALSE, if a swap has occured. The REPEAT...UNTIL 
no’swap#TRUE loop is repeated until no two names are 

swapped on a pass through the list. .-The bubble sort is not 
the most efficient sorting technique, but it is perhaps the 
easiest to understand. On the demo diskette you will finda 
quick ’sort procedure which is much more efficient but 

harder to understand. 


It will sometimes be necessary to change the contents of a 
record in the file. This choice is activated by selecting 
6 from the menu. The procedure change’record is shown 
below: 


1610 PROC change ‘record 

1620 PAGE 

1630 PRINT “32238 CHANGE A RECORD s3:2::" 
1640 PRINT 

16350 PRINT 

1660 INPUT “Which record number? "s: no 
1670 IF no<#number THEN 


1680 print ‘record (no) 

1690 INPUT AT 14,1: "Right record 7? (y/n)? ": replys 
1700 PRINT 

1710 PRINT 

1720 IF replys IN "“yY" THEN 

1730 INPUT "Name ¢ "ss names (no) 

1740 INPUT "Street =: ": street$(no) 

17350 INPUT “City s “s city$(no) 

1760 INPUT "Phone : ": phones$(no) 

1770 ENDIF 

1780 ELSE 

1790 flag$:="There are only "+STR$(number)+" records" 


1800 ENDIF 
1810 ENDPROC change’record 


The procedure should be easy to follow. It involves simply 
requesting the user to indicate which item is to be changed 
then allowing the change to be entered. Notice again the 
use of the variable flag# to transmit an error message to 
the menu. 


Selecting user option 7 from the menu allows a record to 
be deleted. A procedure which can accomplish this 
function is as follows: 


1830 PROC delete ’record 

1840 PAGE 

1850 PRINT "sss33s DELETE A RECORD s3s3:33" 
1660 PRINT 

1870 PRINT 

1880 INPUT “Which record number? ": record 
18690 IF record>number THEN 

1900 flag$:="Use a smaller record number!" 
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1910 ELSE 

1920 print ‘record (record) 

1930 PRINT 

1940 INPUT “Is this the right record (y/n)? ": replys 
19350 PRINT 

1960 IF reply$ IN “yY" THEN 

1970 | FOR no:#record TO number-1 DO 
1980 names (no) s =names (no+1) 

1990 street$(no):#street$ (no+1) 
2000 city# (no) s2city$ (no+1) 

2010 phones (no) : phone$ (no+1 ) 
2020 ENDFOR no 

2030 number s:-1 

2040 ENDIF 


2050 ENDIF 
2060 ENDPROC delete ’record 
2070 


After a file has been entered, sorted or modified, it will 
usually be desirable to save it for later use. Choose user 
option 8 from the menu to activate the following 

procedure: 


2080 PROC save'file 

2090 PAGE 

2100 PRINT “s::ss SAVING FILE TO DISK sss:3:" 
2110 OPEN FILE 1,"@Addresses" ,WRITE 

2120 PRINT FILE 1s: STR# (number ) 

2130 PRINT 

2140 PRINT 

21350 FOR no:#1 TO number DO 


2160 PRINT FILE 1: name$ (no) 
2170 PRINT FILE 1: street#(no) 
2180 PRINT FILE 1: city#(no) 
2190 PRINT FILE 1: phones (no) 


2200 ENDFOR no 

2210 CLOSE FILE 1 
2220 ENDPROC save ‘file 
2230 


To save the file, the file must first be opened, indicating 
the number of the file, 1 in this case, the file name, in 
this case simply Addresses, and the fact that the file is 
opened as a WRITE file. Of course you can alter this 
procedure to make it possible to make the file name user 
selectable. Just insert an input statement like INPUT 
"File name? "sfilenamet early in this procedure. You will 
also have to change the procedure load’file to allow user 
choices there too. 


The procedure save’file continues by first saving the 
number of records in the file (PRINT FILE is 

STR#(number)). This information is the first thing to be 
read in when the file is loaded again. The PRINT FILE 
statements are used to transmit the contents of each record 
to the sequential file. Finally the file must be CLOSEd. 
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RANDOM FILES - AN INVENTORY PROGRAM 


To illustrate the use of random files (also called 

direct files), we will describe a simple inventory 

The program Random File Demo can be found on the 
demo diskette. 
LISTing the program before continuing. . 


program. 


You may wish to try LOADing, RUNning and 


The first few lines of the program identify it (and 
facilitate saving) and DIMension the string variables to be 


used: 


0010 // save "@Random File 
0020 DIM codes OF SO, 


Demo" 
parts OF 30 


0030 DIM quantity# OF 3O, pricet OF 3O 
0040 maxquantitys: #25 


Next 
soon 


0050 
0060 
0070 
0080 
0090 
0100 
0110 
0120 
0130 
0140 
06150 
0160 
0170 
0180 
0190 
0200 
0210 
0220 


After this introduction the program will proceed 
program loop as soon as the user presses a key. 
used the same wait for ’keystroke procedure as in 


comes a brief description of the program, 
as the program is RUN: 


PAGE 

PRINT 
PRINT 
PRINT 
PRINT 
PRINT 
PRINT 
PRINT 
PRINT 
PRINT 
PRINT 
PRINT 
PRINT 
PRINT 
PRINT 
PRINT 
PRINT 
PRINT 
PRINT 
PRINT 


displayed as 


“sss RANDOM FILE DEMONSTRATION :::" 


"This program illustrates as simply as" 
“possible how you can store and retrieve" 
“information from a ‘direct’ or" 
“"“random—access’ file." 


“This example serves to save and retrieve" 


“information about a parts inventory" 
“The informationen is arranged: " 

AT 0,5: "code number" 

AT 0,5: "part name" 

AT 0,35: “quantity” 

AT 0,5: "price" 


"Press any key < >..." 


wait for ‘keystroke 


to the main 
We have 
the 


previous program. 


0270 REPEAT 


0280 
0290 
0300 


0320 


show ‘menu 

IF reply#="1" THEN create ‘record 
IF reply$="2" THEN fetch ‘record 
0310 UNTIL reply$=#"3" 


The main loop displays a menu then diverts execution to 
create‘record or to fetch’record in response to a valid 
user response to the menu: 
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O330 PROC show’ menu 

0340 PAGE 

0350 PRINT "sss RANDOM FILE DEMO — MENU sss23" 
0360 PRINT 

0370 PRINT 

O380 PRINT AT 0,5: "“<1> CREATE a record" 
0390 PRINT AT 0,5: "<2> FETCH a record" 
0400 PRINT AT 0,5: "<3> terminate" 

0410 PRINT | 

0420 PRINT 

0430 wait ‘for ‘keystroke 

0440 ENDPROC show ’menu 


If response 1 is chosen, the program allows the user to 
create a record for the inventory file: 


0460 PROC create ‘record 

0470 PAGE 

0480 PRINT "sess: CREATE A RECORD seers" 
0490 PRINT 

0300 PRINT 

0310 INPUT “Which record number: ": no 
03520 PRINT 

03530 PRINT 

0340 IF no>O AND no<=maxquantity THEN 


03550 INPUT "code number: ": codes 

0360 INPUT “part name =: ": parts 

0370 INPUT "quantity : "s: quantity$ 

0580 INPUT "price : "s: prices 

03590 OPEN FILE 1,"Osinventory",RANDOM 128 

0600 WRITE FILE 1,no: code$,part$,quantity$,prices 
0610 CLOSE 


0620 ENDIF 
0630 ENDPROC create ‘record 


The first part of this procedure is just housekeeping. The 
user must enter the reference number (1 to 25) of the record 
to be created. If it is valid, the IF...ENDIF loop is 


‘executed. Notice how the random file is OPENed. The first 


characters in quotes: Os indicate that the primary disk 
drive, drive 0, is to be used. If a second drive were 
avallable and properly connected to the Commodore 64, it 
could be referenced as drive 2. (This has to do with 
Commodore compatibility with the 4000 and 8000 series 
computers which can have two built-in drives.) The WRITE 
FILE statement in line 600 transfers the four data elements 
in the record to the file inventory. 


A few general remarks on random access files are 
appropriate here. Data is stored’ in random files 


in binary forms: 


* The order WRITE FILE causes the data in the 
record to be saved in binary form on the 
diskette, where numbers and text take up a 
certain number of bytes: 


integers take up 2 bytes 
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real numbers take up 5 bytes 
strings use up 2 bytes + the string length 


The 2 extra bytes for strings are added by the COMAL 
system for to keep track of things. 


* The Commodore disk drives 1541 and 2031 only allow 
one RANDOM file to be open at a time. 


* In the catalogue of diskette contents, a random 
access file is classified as a relative file and 
denoted by rel. 


When we wish to retrieve information which has been stored : 
in the direct file inventory the following procedure, @ 
activated by user choice 2 from the menu, can be used: 

06350 PROC fetch’record 

0660 PAGE . . 

0670 PRINT “ez2sss: FETCH A RECORD FROM FILE essee" 

0680 PRINT 

0690 PRINT 

0700 INPUT “Which record numbers ": no 

0710 PRINT 

0720 IF no>O AND no<maxquantity THEN 


0730 OPEN FILE 1,"Oz:inventory",RANDOM 128 
0740 READ FILE 1,no: code$,part$,quantity$,prices 
07350 CLOSE 

0740 PRINT 

0770 PRINT 

0780 PRINT “Inventory item"sno3 “iss " 

0790 PRINT 

o8so0o PRINT “code number: “scode$s 

0810 PRINT “part name =<: “spart$s 

0820 PRINT “quantity : "squantitys 

0830 PRINT "price : “sprices 

0840 wait ‘for ‘keystroke ‘2 


0850 ENDIF 
O860 ENDPROC fetch ‘record 
0870 





This procedure requests the user to enter a record number. 
Then, if a valid record number has been selected, the file 
is OPENed, and the four data elements of the record are read 
using the READ FILE statement and printed out. 
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SUGGESTED IMPROVEMENTS: 


* This simple program could be improved by adding 
a counter to keep track of the total number of 
records in the file. It should be READ as soon 
as the program is started and updated each time 
a new record is added or an old one deleted. 


* Before the program is used for the first time 
the file inventory should be created in its 
maximum size. To do this writes 


CREATE "inventory" ,25,128 
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This way you can be sure that there is enough 
room on the diskette for the complete file. 
Furthermore, access to the diskette will be 
substantially faster, because the system need 
not expand the file as it is used. 


* All the posts can be zeroed with known data. 
This can eliminate the possibility of reading 
undefined records. It also allows the issuing 
of a warning if useful information is about to 
be overwritten. One possibility is as follows: 


OPEN FILE 1: “inventory",RANDOM 128 
FOR nrz:=1 TO 25 DO WRITE FILE 1:spc$(126) 
CLOSE 


(The inventory is hereby zeroed using blanks. 
Of course you must be sure there 1s nothing of 
value in the file before doing this!) 
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MOVING A SEQUENTIAL FILE 


The last program in this chapter is intended to illustrate 
how a sequential file can be transferred from one diskette 
to another. Files written in machine code are binary files, 
and moving them can be a problem. The program name is Move 
Sequential, and it is available on your demo diskette or 
tape. 


The key to this program is the statement 

GETS (<fileno>,<bytes>). By using this statement 
every’thing on a diskette, including separators not read in 
by the INPUT FILE statement, can be read. 


The program opens a user selectable sequential file, reads 
the entire contents into the variable numbers (however 

max. 3000 characters), requests the user to switch diskettes 
and then writes the contents of numbers to a file with the 
same name on the new diskette: 


0010 PAGE 

0020 DIM names OF 40 

OO3O INPUT “Enter file name: "“:names 
0040 OPEN FILE 2,name$,READ 

0050 DIM numbers OF 5000 

0060 WHILE NOT EOF(2) DO 

0070 number $s: +GETS$ (2, 1000) 

0080 ENDWHILE | 

0090 CLOSE FILE 2 

0100 PRINT numbers 

0110 PRINT "Switch diskettes and press any key..." 
0120 dummy$#KEYS 

0130 WHILE KEYS=#CHR#(0) DO NULL 

0140 OPEN FILE 3,“@0: "+names, WRITE 
0150 PRINT FILE 3s: numbers 

0160 CLOSE FILE 3 
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FILE TYPES 


You have noticed that when you view the contents of the 
diskette using the dir order that different types of files 
are stored. At the right next to the file name you will see 
a three-letter abbreviation describing the file type: 


prg program file 

seq sequential file 

rel relative file 

usr user sequential file 


This classification limits the way in which these files can 
be used. For example if you try to LOAD a relative file as 
a program, COMAL will generate an error message. 


You will probably find it useful as you use files more and 
more to indicate what the various files within a certain 
category are used for. You will be working with fonts, 
shape tables for sprite images, listed sequential files 
containing programs, procedures or functions, external 
procedures, display files, textfiles or data files. 


To distinguish these files from one another, and to make it 
possible to show all files of a certain type using the dir 
order, it is useful. to characterize each file with a file 
type code. You might use a four letter code ahead of or 

at the end of your file. For example you could indicate 
that a sequential file consists of a LISTed program as 
follows: 


your program. 1st lst.your program 
A text file from an editor program might be distinguished by 
using .txt at the end of the file name or placing txt. 
at the beginning or .txt at the end: 

letter.txt txt.letter 


Prefixes or suffixes indicating file types could be as 
follows: 


elst lst. for LISTed files 

— dsp dsp. for DISPLAYed files 
2 Ob j ob j. for object code files 
src src. for source code files 
ext ext. for EXTERNAL procedures 
.bas bas. for Basic programs 
txt txt. for text files 
-grO gro. for graphics screen files 
gril gril. 
-spoO spo. for sprite files 
spl spl. 
pre prc. for procedure files 
efnt #nt. for fonts 


The actual choice is of course up to you, but it can ease 
communication among COMAL users if the same attribute 
notation is used. In this connection we recommend using the 
prefix, because this will allow you to catalogue all files 
of the same time using the DIR order. 
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For example, be sure you have a few text files denoted by 
the prefix txt., then try the following order: 


dir “txt.# 
Only files beginning with txt. will be shown. 
If the suffix convention is used, then an order such as: 


dir "77777.sp?" 


will only list sprite files with five character file names. 


FILES AND THE SCREEN, KEYBOARD AND DISK DRIVE 


One of the powerful features of the COMAL language file 
handling system is the ability communicate with the various 
input/output devices of your computer. Up to this point we 
have illustrated communication with the disk drive, but 
communication with screen, and keyboard is also possible. 


In order to direct file operations to a particular device, 
you should use the unit specifier unit. The unit spec-— 
ifier should be followed by one of the following string 
expressions: 


kbs keyboard 

ds: display screen 

lps line printer 

Spr serial port 

Cwe cassette recorder 

u<device>: device (such as Printer-—-Flotter) 
<drive>s: disk drive number (default 0) 


Note that <device> must be a number in the range 0-31, and 
<drive> is a number in the range O-15. For example: 


unit "des" 
will direct COMAL to treat the display as the output device. 


It is also possible to reveal the current unit assignment 
using the special string variable unit. For example: 


print units 
if units<>"lps" then 
unit "css" 


The first instruction simply prints the current unit. The 
second sequence will set the default unit to the tape unit, 
unless the current unit is the line printer. 


A special feature of the file handling system is the symbol 
@ which may be the first character of a file name. If it 
is, then the file will be overwritten if it already exists 
on the diskette. 
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USING YOUR DATASSETTE UNIT 


Although serious file handling really requires the use of a 
disk drive, Datassette users will be pleased to find that 
many file operations can be done with a tape unit. Opera- 
tions with sequential files will, however, be considerably 
Slower than with a disk drive. Random access files cannot 
be used with a tape unit. 


USING THE 1520 PRINTER-PLOTTER 


One of the many useful peripheral devices which you can 

attach to your Commodore 64 is the 1520 Frinter-Flotter. It 

can be used both for listing programs and results and for © 
drawing graphics images of high quality in up to four 

colors. 


It is quite easy to activate your Frinter-Plotter from 
COMAL. If the Frinter-Plotter is properly attached to your 
serial bus (or to the extra serial bus connection at the 
rear of the disk drive), you can try the following 
demonstration. Be sure that the 1520 is turned on. Enter a 
brief program, then type: 


list "“ués 
Your program should be listed on the Frinter-Flotter. 


Other operations with the Frinter-FPlotter are handled in a 
Similar fashion. Just remember to use the device 
specification “ués. 


You will find a demonstration program 1520 Plotter Dem on 
the demo diskette and listed in Appendix H. Try out this 
program and study the listing to see how to use your 1520 
with COMAL. 


REVIEW 


In this chapter several important topics @ 
pertaining to the use of COMAL files have been 
covered: 


file operations on programs and procedures 
using sequential files for numbers and strings 
using random files 

file types 

using files with input/output devices 

using the 1520 Printer-Plotter 





* * ke kk * 


You should be familiar with the following concepts after 
working through this chapters 
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file 

storage medium 

sequential file 
random-access (direct) file 
record 

data element 

bubble sort 

file types 

device specifications 


The following COMAL instructions have been discussed: 


SAVE - LOAD 

LIST —- ENTER —- MERGE 
OPEN FILE —- CLOSE FILE 
PRINT FILE — INPUT FILE 
WRITE FILE —- READ FILE 
RANDOM 

CREATE 

GETS 


In addition to the examples of the use of files shown in 
this chapter, you may find it helpful to study details on 
the formal syntax of these orders in Chapter 4. 


The following programs have been discussed in this 
chapter. They are also to be found on the demo diskette: 


Addr List Demo 
Random File Demo 
Move Sequential 
1320 Plotter Dem 


The best way to learn about files is to use them to make 
them work for you. You can use the programs in this chapter 
as a starting point. Change them and extend them. You will 
find that mastery of the art of file handling is one of the 
most valuable skills that you will learn while using your 
Commodore 64 computer and the COMAL cartridge. 





-240- 





-241- 


Chapter F — 


PERIPHERAL DEVICES 


INTRODUCTION 


Your Commodore 64 computer is provided with several 
different means for attaching it to other devices. Compared 
with other computers in its class there is a generous 
allocation of input/output connectors included in the base 
price of the computer: 


* JTEEE serial bus —- for connecting the C64 to disk drive, 
printers or other devices, 


* Datassette tape unit interface, 
* Parallel input/output port, 


* Cartridge port for connecting games, applications 
programs or language cartidges like COMAL, 


* Control ports (2) for connecting joystick, paddles, 
etc. 


As you can see from Chapter 5 
on COMAL Fackages it is quite 
easy to integrate the use of 
joysticks, paddles or a light- 
pen into your programs. The 
use of the IEEE serial bus for 
communicating with disk drives 
or printers has been covered 
in Chapter 6 on COMAL Files. 
Those who have a Datassette 
unit are also familiar with 
its use for saving and re- 
trieving programs and files. 





In this chapter we intend to di- 
rect our attention to the use of 
the RS-232C interface, 


IEEE cartridges, and par- 
ticularly to the parallel port. 


THE R&-232C INTERFACE 


RS-232C is an industry standard which defines a particular 
type of serial communication. Data is transmitted as a 
series of pulses one after the other along a single wire. 
Figure 7.1 illustrates the transmission pattern which 
corresponds to the serial ASCII-code for the single letter 
C. This letter has the ASCII decimal code 67, 
corresponding to the binary number 01000011. 
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start parity stop 
bit bit bit 
| LSB MSB 
1 q 


0 T 2T #3T #4T «ST 6T VT BT QT 10T 


k-—<_——_—_——______4 
110000 1 


Figure 7.1: The letter C is transmitted in serial form 
according to the RS-232C standard. Note that 
only 7 bits are sent, least significant bit 
first! 


The data can be sent in asynchronous form. The time 
period for the transmission of a complete character can be 
divided into 10 equal time intervals. Two well-defined 
voltage levels determine whether the signal in a given 
interval is to be interpreted as high or low. In this 
discussion we will refer to logic levels, but keep in mind 
that in practice these levels will appear as voltage 
variations in the RS-232C connector cable. 


Every character signal begins with a start bit. It is 

logic O in the example shown in Figure 7.1. The start bit 
is used to synchronize the receiver with the transmitter. 
When detected, the start bit starts a clock with period T 
which then coordinates the reading of the serial line. The 
receiver can take periodic samples to determine whether each 
bit is a logic 1 or a logic Oo. After seven samples the 
binary code of the character is available in the receiver's 
storage register. 


The next bit is the parity bit which indicates to the 
receiver whether an even or odd number of 1’‘s (or O‘s) 

is transmitted in a given character code. For systems with 
even parity the parity bit will be high (logic 1) if an 
even number of high bits are transmitted and low (0) 

if an odd number are sent. This can be checked by the 
receiver to ascertain whether or not transmission errors 
have occured. Finally, a stop bit is sent to indicate the 
end of the character transmission. 


The RS-232C standard also specifies a protocol which is 
designed to facilitate communication. For example CTS 
(Clear To Send) and RTS (Request To Send) signals are 
defined. Furthermore, the voltage levels for logic 1 and 
logic O are specified as -12 and +12 volts respectively. 
The complete specification can be found in textbooks on 
electrical engineering. The information which follows 
should be adequate to allow you to begin using the RS-232C 
interface with COMAL. 


The electrical connections to an RS-232C port are 
standardized using the DB-25 connector: 
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pin signal code 
1 protective ground GND 
2 transmitted data SOUT 
3 received data SIN 
4 request to send RTS 
5S clear to send CTS 
ra data set ready DSK 
7 signal ground GND 
8 Carrier detect DCD 

9-17 e-.- not used ... 

18 ring indicator RI 
19 »~.-. not used ... 

20 data terminal ready DTR 

21-25 »~»-. not used ... 





Figure 7.2: The standard pin connections for the RS-232C 
interface and the pin arrangement for the DB-25 
connector are shown. 


All available RS-232C control signals are rarely used in 
actual communications setups. It is often adequate to use 
only the two data channels SIN and SOUT. An interface of 
this type is sometimes called a three line interface since 
it consists only of an input, output and ground. 





Your Commodore 64 can handle the three line interface as 
well as the complete RS-232C interface with all control 
signals. However the Commodore interface deviates from the 
RS-232C standard with respect to voltage levels. The 
Commodore 64 uses O volts for logic 1 and +S volts for 
logic 0. The RS-232C signals are available on the 
Commodore user port as indicated in Figure 7.23: 


Commodore RS-232C signal Signal DB-235 standard 
user port description direction connections 

A GND ol 1 

B SIN input mi 

Cc SIN input 3 

D RTC output 4 

E DTR output 20 

F RI input 18 

G DCD input 8 

K CTS input bar 

L DSR input & 

M SOUT output < 

N GND = 7 


(NB: B and C should be connected together ) 
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12 3 4 5 6 7 8 9 10 11 12 





Commodore 64 user port pin connections. 


Figure 7.3: The Commodore RS-232C connections are available 
on the user port on the rear left-hand side of 
the computer. 


It is very important that the voltage levels of the 
Commodore 64 RS-232C interface are adapted to the +/- 12 @ 
volts present on other equipment. A standard adapter which 
accomplishes this is available from your Commodore dealer. 

Diagrams for such devices can also be found in the hobby 

literature, so that you could build such an interface 

yourself. 


WARNING: Incorrect connection of the RS-232C 
interface to other equipment using +/- 12 volts 
can cause permanent damage to your Commodore 64 
computer. 
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Using COMAL you can select a number of parameters toa 
accommodate the requirements of the communications equipment 
to which your Commodore is connected. The following COMAL 
program illustrates how to receive data using the RS-232C 
interface: 


0010 OPEN FILE 1,"sp:bi200dGslpe" ,READ 
0020 

0030 REPEAT 

0040 a$;:=GET$(1,1) 

0045 PRINT a$, 

0050 UNTIL a$=CHR$ (255) OR KEYS$< >CHRS (0) 


ey e 
0070 CLOSE FILE 1 


0080 
0090 END "End" 


Line 10 opens a logical file numbered 1 and specifies the 
following information: the file opened is to be a file which 
READs the serial port with a baud rate of 1200 (b1200), 8 
data bits (d8), 1 stop bit (#81) and even parity (pe). 

In general the following coding can be used to specify the 
parameters of the RS-232C interface: 


parameter syntax range default 

baud rate b<baud> 90-2400 b300 

data bits d<num> 3-8 d7 

stop bits s<num> 0-2 s2 

parity p<type> n=none pn 
e=even 


o=odd 
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Examples: 
“sp:" . 500 baud, 7 data bits, 2 stop bits, no parity bit 
“sp:bé00" 600 baud 


“spsb1i200d8sipe" 1200 baud, 8 data bits, 1 stop bit, even parity 


Notice that the serial channel will remain open and the 
program continues to execute the REPEAT-UNTIL loop in lines 
30-SO until a transmitted character code corresponds to 
decimal 255 or any key is pressed. 


Data transmission files are opened in the same way, using 
WRITE instead of READ. Notice also that an RS-232C inter—- 
face file which has been OPENed must of course be CLOSEd 
again as soon as possible. It is not possible to use the 
tape recorder or the IEEE serial bus (i.e. the disk drive) 
while the RS-232C interface is in operation. Thus data 
which 1s received must be stored in program memory as it 
enters the RS-232C port and then saved to disk later. 
Similary, you must prepare a data file in working memory, 
OPEN the RS-232C file, send the data, then CLOSE it before 
using the disk drive. 


TEEE CARTRIDGES 


It is possible to purchase a variety of IEEE interface 
modules which attach to the Commodore 64 cartridge port. 
Such devices are available from your Commodore dealer (ask 
for the IEEE 488 cartridge) as well as from other sup- 
Pliers. One of these is called the Bus Card II and is 
available from the company Batteries Included. These 
cartridges can be used with your COMAL language cartridge, 
for the cartridge bus is accessible in these products. The 
IEEE cartridge is inserted in the cartridge port, then your 
COMAL cartridge can then be inserted in a slot in the IEEE 
cartridge. 


The main advantage of the extra IEEE cartridge is that you 
can then use your Commodore to communicate with high 
Capacity, high speed disk drive units like the Commodore CBM 
8050 and 8250 devices. 


If you have access to other cartridges such as game 
cartridges, spreadsheets and the like, you must remove your 
COMAL cartridge in order to use them. In that case be 
careful to TURN OFF THE POWER to all units in your system 
before switching cartridges. 


THE PARALLEL PORT. 


One of the most useful features of your Commodore 64 is the 
parallel input/output port, the 1/0 port for short. The 
I/O port can be used to communicate with the outside world. 
You can use the port as an output for control purposes (to 
run a machine, switch lights on and off, automate an elec- 
tric train, etc.). The port can also be used as an 

input to gather information (measure voltages, 
temperatures, and other quantities). In this section we 
will describe a simple application to illustrate how the 
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port can be used. 


This section is not intended to be a complete description of 
the I/O port. The best place to find details about the 
parallel port is in the Commodore 64 Programmer ‘s Reference 
Guide available from your Commodore dealer. In the fol- 
lowing only as much information as necessary for you to 
understand the examples willbe presented. 


The physical location of the port is the edge connector at 

the far right side of your Commodore 64 when viewed from the 

rear. The location of the port slot is shown in Figure 1.1 

in Chapter 1. Electrical pin connections for the parallel 

port are shown in Figure 7.3 earlier in the present chapter. 

To make an electrical hook-up to the port, you will need a @ 
24-pin edge connector plug, available from your dealer or 

from most electronics supply houses. Note that the 

connections we will use are as follows: 


connection . signal 

pin 1 (or A) ground 

pin 2 +S vdc (max 100 mA) 
pin C port B bit O 
pin D port B bit Il 
Pine ‘port B bit 2 
pin F port B bit 3 
pin H port B bit 4 
pin J port BK bit 5S 
Pin K port B bit & 
pin L port B bit 7 


One convenient way to attach your Commodore 64 to external 
equipment is by means of a meter long piece of 10 conductor 
ribbon cable. Solder the 10 leads to the pins of the 24-pin 
edge connector as indicated above. Solder the other end to 
a standard DB-25 miniature 25 pin connector. The pin 
assignments for the DEB-25 connector are shown in Figure 7.2. 
These connectors are quite readily available and inexpensive 
as they have been adopted as a standard for the RS-232C 
interface. Label the connectors carefully. If you make a 
mistake applying voltages to these connectors, you could & 
damage your computer. 


The 25-pin connector is recommended because you may decide 
to add more connections for advanced projects later on. Use 
pin t on the DB-25 for ground, pin 2 for +5 volts and pins 
18-25 for port B bits O-7. 


WARNING: Do not carry out these projects without 
some prior experience working with electrical 
connections. Never make connections to the 
computer unless all power has been turned off. 
Although the projects are not difficult, incorrect 
connections to your Commodore 64 could damage the 
computer. If you are not sure how to proceed, 
have an electronically inclined friend give you a 
hand, or ask your dealer for advice. 
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To illustrate connection of an external device to the I/O 
port, we have chosen a simple control praject. Once you 
have understood this example, you should be prepared to 
tackle more ambitious tasks. 


Suppose that we have a closed loop of track, one electric 
train and a station. We want the computer to allow the 
train to run around the loop until it approaches the 
station. It must stop at the station, wait for a predefined 
period, then run around the loop again. 


In order to accomplish this control process, two items of 
hardware are required: 


* A transistor and relay must be available to switch 
the power to the train tracks on and off. This 185 easily 
accomplished using a few parts readily available from an 
electronics hobby store. 


* A sensor must detect the passage of the train just 
before the station. This can be done using a Darlington 
fototransistor and a small light source beamed across the 
track to strike the sensitive area of the fototransistor. 
The collector should be connected to the port bit as 
described below, and the emitter should be connected to 
ground. 


Note that in order to control the train, we will need to use 
two bits of the parallel port. We are free to choose. 

Let’s use bit O for the light detector and bit 1 for 
starting and stopping the train. 


Each bit of the parallel port B can serve as an input or an 
output. This 15 indicated by storing the appropriate number 
in the data direction register for the port, in this case 
port B. The addresses for the data direction register and 
for port HB are as follows: 


decimal hexadecimal 
port B address 36977 #DDO1 
data direction register 56579 #DDOS 


The number stored in the data direction register (often 
abbreviated ddr) determines whether the individual bits of 
port B will act as inputs or outputs... It is easiest to 
understand the situation using binary numbers. AO bit in 
the ddr means the corresponding bit of port B will act as an 
input. A 1 bit in the ddr sets the corresponding bit of 
port B to an output. For example, binary OQ000010 

(decimal 2) stored in the ddr will make port B bit O an 
input and bit 1 an output. This is just what we need to 
control the train. 


Because COMAL will accept binary numbers directly, it is not 
necessary for the programmer to translate the binary number 
to its decimal equivalent. The programmer must simply 
remember to preceed binary numbers by the symbol Z%. 


The program Train Demo is available on your COMAL demo 
diskette or tape. It is also listed completely in Appendix 
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H. 


Line 10 indicates the name of the file. In line 30 the 
screen is cleared by PAGE. Lines 40-90 print the following 
message on the screen: 


ELECTRIC TRAIN DEMO 


Your train should start at the station 
with the passage detector just behind 
the last car. Start the train and then 
press any key to turn control over 

to your computer... 





Notice line i100: 
0100 WHILE KEY$=CHRS$(0O) DO NULL 


These instructions keep the program in a loop until any key 
is pressed. The system variable KEY? will then be different 
from the null string CHR#(0), and the program will continue. 


The main program starts in line 200. The procedure 
define’variables in line 220 defines the addresses of port 

B and its ddr, and the initial value of the variable 
position is set to 1. Note that COMAL allows the 

programmer to indicate the port B and ddr addresses directly 
in hexadecimal form. Hexadecimal numbers are preceeded by 
$. Note also the convenient variable names: 


0680 PROC define’ variables 
0690 port ’b:=$dd0Ol 

0700 port ‘’b ‘ddr: =$dd03 

0710 position:=1 

0720 ENDPROC define ‘variables 
0730 


The apostrophes ’ are necessary to bind the individual 
words together, so that COMAL will interpret them as a 
single variable name, just as with procedure names. The 
variable position will be used to control a pointer on the 
screen display, indicating the action of the program. 


The procedure in line 230 sets port b. This is done as 
follows: 


0740 PROC set ‘port’B 
0750 POKE port ’b’ddr,2 
0760 POKE port’b,2 
0770 ENDPROC set ‘port ’B 
0780 


The decimal value 2 corresponds to the binary number 
00000010 and makes bit O an input and bit 1 an output. 

Bits 2-7 are not used in this case, so it doesn’t matter how 
these bits in the ddr are set. 


The train is started by the procedure start ’train: 
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0480 PROC start ‘train 

0490 POKE port ’b,PEEK(port’b) BITOR 2 
0300 advance ‘pointer 

0310 ENDPROC start ‘train 

0320 


The POKE order places the number PEEK (port’b) BITOR 2 in 

the port B address. The BITOR operation is described in 
detail in Chapter 4. It assures that bit 1 is) high. This 
Signal is amplified by the transistor and activates the 
relay, starting the train. The procedure advance’‘pointer 
moves an arrow on the screen to the next item of the screen 
list, jumping back to the start of the list at the beginning 
of each loop. 


0790 PROC advance ‘pointer 
0800 PRINT AT 10+position,2: " " 
0810 IF position<4 THEN 


0820 position: =position+1 
0830 ELSE 
0840 positions: =2 


0B50 ENDIF 

0860 PRINT AT 10+position,2: ">" 
0870 ENDPROC advance ‘pointer 

0osso 


The next procedure encountered is the print’list 
procedure. It simply makes a list of items on the computer 
display: 


> train running 
train passes light 
train waiting at station 


Pressing any key will stop the train 
next time it stops at the station... 


The pointer shows the state of the program. 
Now the program enters the main loop: 


0270 REPEAT 

0280 check ‘light 

0290 delay (1.5) 

0300 stop train 

0310 delay (10) 

0320 start ‘train 

O330 UNTIL KEYS< >CHRS (0) 
0340 stop ‘train 

0350 PAGE 

0360 END "Au revoir!" 


This loop will continue to run until any key is pressed. If 
KEY is anything but the null string CHR#(0), the program 
ends. 


The procedure check'’light examines the state of the bit 0 
of port B. This is done as follows: 
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0330 PROC check ’light 

0340 WHILE PEEK (port’b) BITAND 1 <> 1 DO NULL 
03350 advance’ pointer 

03540 ENDPROC check ’light 

0370 


The precise operation of the BITAND operator is described in 
Chapter 4. In this case the condition PEEK(port‘’b) BITAND 

1 <> 1 will be FALSE terminating the laop when bit O 

becomes high. This will happen if the light shining on the 
fototransistor is interrupted. With the collector attached 
to port B bit O, the emitter grounded (the base is not used) 
and the transistor illuminated, the collector-emitter 
resistance is low (about 100 ohms), pulling bit O to low. 

If the transistor is not illuminated, the resistance becomes 
high (typically 1 Mohm), and bit O returns to the high 
state. 


Before stopping the train, the program executes the 
procedure delay(1i.5): 


O380 PROC delay (sec) 

0390 TIME O 

0600 WHILE TIME<sec*60 DO NULL 
0610 ENDPROC delay 

0620 


Note that the variable sec is passed to this procedure. 
It corresponds to the delay time in seconds. TIME resets 
the internal clock. The loop in line 600 continues until 
the number of timing units (jiffies = 1/60 sec.) exceeds 
sec#60. Note of course that the parameter value 1.5 can 
be changed ina particular situation to assure that the 
train stops as desired at the station. 


The train is stopped by the procedure stop’train which 
simply changes bit 1 to the low state. Note that a more 
refined way to stop (or start) the train would be to rapidly 
turn the bit off and on, altering the duty-cycle (the 
proportion of the time the bit is on) gradually from 1 to O 
(or 0 to 1) over a time interval. This will cause the train 
to gradually slow down (or speed up) ina more realistic 
fashion. If you decide to do this, replace the relay with a 
power transistor circuit to control current flow to the 
track. 


FILE TRANSFER BETWEEN COMPUTERS 


It is possible to transfer sequential files between your 
Commodore 64 and other computers. The most common two way 
communications channel is via the RS-232C connector using 
the RS-232C standard described earlier in this chapter. To 
achieve this it is essential that the computer with which 
you want to communicate also has an RS-232C input and output 
connection. Furthermore, because the C-64 RS-232C interface 
uses TTL-logic levels, you will require a converter module 
to change 0/75 volt signals to the RS-222C standard levels af 
-12/+12 volt. It is also possible to transfer files via the 
parallel input/output port (the user port). 
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THE CONTROL PORTS 


In addition to the many communications possibilities already 
described, your Commodore 464 computer also has two 

control ports (sometimes called game ports). The use of 
these ports from COMAL has already been described in the 
section in Chapter S on COMAL packages. 


In addition to 2 x 5 switch inputs (JOYAO-2, JOYBO-3, BUTTON 
A and BUTTON B) available at the two control ports, a total 
of 4 different analogue inputs are also available via the 
game ports. These inputs are POTAX, POTAY, FOTBX and POTBY. 
(Internally the SID has just 2 ADC’s and an analogue 
switch.) Pinouts and connections are as follows: 





pin game port A game port B 
1 JOYAO JOYBO 

2 JOYAL JOYB1 

= JOYA2 JOYB2 

4 JOYAS JOYB2 

3 POTAY FOTBY 

& BUTTON A BUTTON B 

7 + SV + SV 

8 GROUND GROUND 

9 POTAX POTBX 


NB: Maximum load on the + SV supply is SO mA. 


Note that you will need a standard DE-9 female connector 
to attach experiments to the game ports. 


The switch inputs can indicate to a program whether a given 
switch is on or off. Examples of how to use these 
Signals are available in Chapter 5. 


The analogue inputs go to A/D converters which are used to 
digitize the positions of potentiometers on paddles. The 
conversion process is based on the time constant of a 
capacitor tied from the FOT pin to ground, charged viaa 
potentiometer tied from the POT pin to +S volts. The 
component values may be estimated from the relation: RC = 
4.7E-4. In this equation R is the maximum resistance of 
the potentiometer and C is the capacitance. The larger 
the capacitor, the lower the uncertainty in the POT value. 
The recommended values for. R and C are 470 kiloohm and 
1000 pF. Note that a separate potentiometer and capacitor 
are required for each POT pin. 


Although the POT inputs in the game ports were designed to 
measure the rotational position of a potentiometer, any 
variable resistance can be used. For example to measure 
temperature simply replace the potentiometer with a therm- 
istor in the proper resistance range. Other resistive 
sensing devices can of course be used to allow automated 
recording of pressure, liquid level, illumination or other 
physical quantities. For example the following program 
illustrates how you might construct a simple digital 
thermometer using the game port inputs: 
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0010 // save "@Thermometer " 

0020 USE paddles 

0030 // capacitors 1000 pF 

0040 // thermistor: 100 K at 20 degrees 
OOS0 azs=1z3 6:20 

0060 PAGE 

0070 PRINT "DIGITAL THERMOMETER" 

0OO80 PRINT AT 53,1: “Thermistor and capacitor must be con-" 
0090 PRINT "nected to controlport 1..." 
0100 

0110 // Main program 

0120 LOOP 

0130 check ‘paddle(1) 

0140 convert (average) 

01350 print ‘temperature 

0160 EXIT WHEN KEY$<>"" 

0170 ENDLOOP 

0180 END // hovedprogram 

0190 . 

0200 PROC check ‘paddle(port) 

0210 total :=0 

0220 FOR is#1 TQ 30 DO 

0230 paddle(port,a‘paddle,b ‘paddle,a’button,b button) 
0240 total :=totalt+a ‘paddle 

0250 ENDFOR i 

0260 aver age: total /50 

0270 ENDPROC check ‘paddle 

0280 

0290 PROC convert (average) 

0300 temp! =a*taver age+b 

0310 ENDPROC convert 

0320 

O330 PROC print ‘temperature 

0340 temp: =INT (temp*#10) /10 

0350 PRINT AT 10,10: "T = o" 
0360 PRINT AT 10,14: temp 

0370 ENDPROC print ‘temperature 

0380 


The first part of the program (lines 10-100) are just 
introductory information, a display message and definition 
of the constants a and b. Notice that these are set 

equal to 1 and O respectively in line 50. This causes 

the program to just printout ADC values (0-255) with no 
conversion to temperature. These values can first be found 
after you have constructed a test circuit and calibrated 
the sensor which you plan to use. 


Notice the structure of the rest of the program. The main 
program is from line 110 through line 170. It consists of a 
REPEAT—-UNTIL loop which will be terminated if any key is 
pressed. In the loop information is fetched from the paddle 
port by the procedure check’paddle(1). Then this quantity 
is converted to a temperature value using the procedure 
convert (average). Finally the procedure 

print ‘temperature displays the computed temperature on the 
display screen. 


Make a trial setup using a 1000 pF capacitor and a 
thermistor (NTC or PTC resistor) with a room temperature 
value of about 100 kohm. Connect your test circuit to the 
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control port as shown in the following figure: 


(7) +5 voit 


(9) POTAX 
C (ca. 1000 pF) 


(8) GND 


Figure 7.4: Many different sensor types can be attached to 
the control ports. You can make use of up to 4 
analogue inputs to the two control ports. 


If the program is now run, the measured ADC values will be 
shown on the screen. Draw a graph displaying the 
temperature in degrees as a function of the ADC values. If 
the graph is approximately linear in the region of 
interest, you can compute the constants a and b as 

follows: 


Read two coordinate pairs from your graph (X1,Y1) and 
(X2,Y2). (X1 and X2 correspond to ADC values, and Yi and Y2 
correspond to temperatures. ) The constant a can now be 
found using the formula: 


a © (¥2 - Y1)/(X2 - X1) 


This is the slope of the line you drew on your graph. We 
found the following values in our test setup which used an 
NTC resistors: (183,25) and (215,20) -—- temperatures are in 
degrees centigrade. I.e. the program showed 183 as ADC 
value when the sensor temperature was 25 degrees C, and 215 
when the temperature was 20 degrees. Thus a equals -0.178 
in this case. To find b you can now used the equation: 
‘temp = ataverage + b (used in the procedure convert). 
Inserting average = 183 and temp = 25 into this equation 
yields a value for b of 57.6. If you change line 50 to 
reflect the new values you have found for a and b, the 
program should print out the temperature when you run it 
again. 


If you want to calibrate a sensor over a wider range of 
temperature, you can use e.g. an exponential function to 
achieve a better calibration than the linear approximation 
we have used in the illustration above In this case you 
must revise program line 300. 
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REVIEW 


In this chapter we have considered a 
range of possibilities for the use of 
the wealth of interfacing facilities 
available with your Commodore 4&4 
computer. You are encouraged to 
experiment with the RS-232C interface, 
the parallel port and the game ports to 
learn more about them. 





You will find more information about these ports in the 
Commodore 64 Programmer ’s Reference Guide. A great deal 
additional information is also available from the popular 
literature about microcomputers. 
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COmMAL AND MACHINE LANGUAGE 


WHAT IS MACHINE LANGUAGE? 





The “brain" in every microcomputer is a central 
microprocessor. Your Commodore 64 is no exception. There 
are a number of different types of microprocessors avail- 
able, each with its own set of instructions. The Commodore 
64 uses a more advanced version of the 6502, the 64510. It 
uses the same instruction set as the popular 6502 but has 
additional built-in !/70 facilities. The oniv language a 
microprocessor can interpret directly is machine ianguage. 
Any higher level ianguage must ultimately communicate with 
the microprocessor using its native lanquage. 


Inside your COMAL cartridge are a large number of machine 
code routines termed collectively the COMAL svstem. When 
the computer is turnea on. the COMAL system automaticaliv 
takes charge of the Commodore 64. Another important machine 
code program in your computer is the operating svstem 

which takes care of communication with the kevboara, screen 
editing and other housekeeping chores. When a COMAL program 
is "run", appropriate machine code routines are brought into 
plav to achieve the actions which your COMAL statements 
reauire. 


It should be made ciear at the outset, that this chapter is 
not intended to serve as a tutorial in machine ianquage 
programming. We assume here prior knowledae of 6502 machine 
language programming. The material presented here is 
substantially more difficuit than the material in previous 
chapters. If vou want to iearn more about 6502 machine 
language, a number of excellent books are available. You 
might want to begin with Lan Sinclair s Introducing 
Commodore 64 Machine Code (‘Granada Fublishing. London. 
1984). The Programmer ’s Reference Guide available trom 
your Commodore dealer is also a valuable resource. 


Machine lanquage will probably be easier to learn if you can 
share the learning experience with others who nave similiar 
interests. In this connection the many Commodore 64 and 
Commodore COMAL users groups-can provide useful 
opportunities of exchange of information. Here are some 
addresses which may be helpfuis 


In the USA: COMAL USERS’ GROUP, 5501 Groveiand Terrace, 
Madison WI 33716 


In Canada: TPUG Inc., COMAL USERS’ GROUP, 1912-A Avenue 
Rd... Ste.#1 Toronto, ONT MSM 4A1, CANADA 


In England: TCPUG, ATT: Brian Grainger, 73 Mine Head Way, 
Steven Age, Hirts SGi 2HZ, ENGLAND 


In this chapter you will find an overview of the use of 
computer memory by the COMAL svstem. Next comes step by 
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step instructions showing how you can incorporate your own 
machine code routines as a package in a COMAL program. 


Machine language is much easier to work with, if you have 
access to a 6502 assembler program. Such a program allows 
you to prepare a program using symbolic machine code using 
mnemonic codes instead of programming directly in 
hexadecimal notation. A disk drive will also make working 
with machine language easier. On the demo diskette (or 
cassette) you will find a textfile with the name C4&4SYMB. 
It contains a list of all instructions which are relevant 
when doing machine language programming with your Commodore 
64 and COMAL. This textfile should be included in the 
assembler source code with COMAL packages. 


It is also possible to prepare a machine language program 
directly in memory from a COMAL program by using POKE 
orders. In this way a machine code program can be stored in 
an available area of computer memory then started from a 
COMAL program by using SYS <start address>. The last 
instruction in the machine code routine should be an RTS, 
which causes program execution to return to COMAL. It is, 
however, not possible using this method to prepare machine 
code program packages which can be LINK’ed to COMAL 
programs. In this chapter we will only treat the 
preparation of machine code programs which can be LINE ’ed to 
a COMAL program. 


The use of machine code routines is an integral part of the 
COMAL svstem. When designing machine code facilities. three 
primary goals have been strived for: 


* Machine code routines should be easy to use - aiso for 
users without knowledge of machine code. 


* Access to machine code routines should be by name, 
thereby eliminating confusing details like memory 
addresses. 


* Machine code routines should be affected by commands 
like NEW and RUN. In this way packages behave as it 
they are an integral part of the COMAL system. 


There are three commands/statements in COMAL which are used 
in connection with the definition, use and removal of 
machine coded routines: 


LINK <filename> // Enter a module file 
USE <package> // Define procedures 
DISCARD // Remove all modules 


These commands (USE can also be used as a program statement) 
will be explained in detail. Machine code routines use the 
procedure and function mechanism in COMAL and allow 
therefore all parameter types. 
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MODULES 


The LINK command fetches a machine lanquage module (object 
file) from the library which has been prepared by the 
assembler. This module contains information which specifies 
where the machine code is to be located in memory. COMAL 
can control up to 10 such modules at any one time. At least 
= modules, containing the following, are alwavs defined: 


(Module 1) (Module 2) 

english graphics sound 

dansk turtle joysticks 

system sprites paddles 
font lightpen 


These modules need not be LINE’ed. tor thev are aireaay 
available in the COMAL cartridge. Modules can be removed 
again using the DISCARD command. However the above 
mentioned standard modules can NOT be removed. Recause the 
modules are not named, all other modules wiil alwavs be 
deleted by DISCARD. Modules can be made permanent (be 
ROM’ed), whereby they can not be DISCARD’ ed. Non-per manent 
modules are treated as if they were part of the program in 
working memory. A SAVE order will store all non-permanent 
modules with the COMAL program in the same prg file. When 
LOAD, RUN or CHAIN is used, thev will be read in again (be 
LINKed). 


PACKAGES 


A module can contain O, 1 or more packages. 


PROCEDURES AND FUNCTIONS 


A package can contain O. 1 or more procedures or functions. 
Two main elements constitute each procedure or function: 


* A procedure header, which specifies how many ano what 
type of parameters are to be passed to the procedure. 


* The pracedure bodv, i.e. the machine code which is to 
be executed when the procedure is calied. 


This drawing illustrates the hierarchal structure: 


—- module 1 - ! — module 2 - !' - module 3 - ! -... module n 
1 1 . i 
- package 1 - !' - package 2 - ! — ....- package m — ... 
: , 
- proc il - ' = proc ..2> P= oroc 2 °= 4. .2proc ‘pss 
i] 4 ‘ t 
header i header 2 header 3 header p 


bodv 1 body 2 body 3 body p 


Chapter 8 - - 28- MACHINE LANGUAGE 


The USE statement performs the following actions: Each 
module, starting with the last one to be read in, is checked 
to see if the name following USE is to be found in the list 
of package names in this module. If the name is found, then 
the procedures and functions found in this package are 
defined. The locations of. the procedure headers are noted. 


SIGNALS 


When COMAL carries out an operation which can affect modules 
or packages, a signal is issued regarding the operation in 
question. The module or package may or may not react to the 
Signal. There are two types of signals: 


* A signal is sent to a package when a USE statement is 
encountered which activates the package. The signal is 
in effect a call to a routine which is local for the 
package. As an example of what such routines may da, 
the TURTLE package selects the SPLITSCREEN display, 
when the command USE turtle is given. The main purpose 
of the routine is to initialize the variables in the 
package. 


* On system start or when LINK, LOAD, DISCARD, NEW. RUN, 
CHAIN are issued (and in certain other special 
Situations), signals are sent to all modules. The 
Signal causes a cali to a routine in the mocule (and 
thus common to all packages in the module). The 
Purpose of the signal call is to integrate all packages 
in the module into the COMAL system (after start-up, 
LINE, LOAD), or to return the COMAL system to its 
Original state (after DISCARD, NEW). If a package is 
to use interrupt (IRQ), then the module can link the 
interrupt routine using LINK and disconnect it again 
with DISCARD. 


HOW IS MEMORY ORGANIZED? 


The following diagram illustrates the entire memory of your 
Commodore 64 (the first 3 columns), the memory in the COMAL 
cartridge (the next 4 columns), and finally the user- 
programmable EPROM expansion (the last 2 columns). The 
expansion option consists of an empty EPROM socket in the 
COMAL cartridge. This cartridge can hold an SKB-, 16KB-, or 
32KB—-EPROM. 





Chapter 8 - -759- MACHINE LANGUAGE 


C64 C464 C64 Cartr. Cartr. Cartr. Cartr. Cartr. Cartr. 
RAM Forts ROM ROM ROM ROM ROM EPROM EPROM 


KERNEL 


COMAL CHAR 


BASIC! 
COMAL |COMAL [COMAL | COMAL 
pagel [page2 |pages |page4 [pages 


64K 






JOK 





v2K 


48K 











RAM is partitioned as follows: 


O- 1ikKB System variables for KERNEL, COMAL, processor 
stack. 
1- 2KB Screen memory. 
2-32KB Storage for COMAL program, name table and stack. 
Here is also room for packages, which take up user 
memory. The character set, if used, is at 27- 
S2KB. 
32-48kKB Is unused. Packages can be placed here without 
reducing available program working memory. 
48-S2kKB COMAL system variables, variables for standard 
packages. 
32-S6KB Variables for function keys, moving sprites, 
sprite drawings and color intormation for 
graphics. 
56-64KB Graphics bit map. 


The I/O area contains the input/output ports. All 
communication with the surrounding world is carried out via 
these ports. The color memory for the text screen is also 
located here. This color memory is (unfortunately) shared 
with multi-color graphics. 


The following ROM areas are located in the C-64: 


40-48kKB BASIC interpreter 

52-S6KB Standard double character set (font) 

36-64KB KERNEL. This is the Commodore 64's operating 
system. It contains among other things routines 
for communication with the screen, cassette tape, 
disk drives and the RS232 interface. 


The COMAL cartridge is partitioned into four pages, each 
containing i6KB. They are all located in the address range 
32-48KB. In this way the 64kKB COMAL interpreter only takes 
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up 16KB in your Commodore 64. 
The contents of the cartridge ROM’s are as follows: 
Fage Ii COMAL starts here when the machine is turned on. 


It contains the math. routines, commands and the 
packages ENGLISH, DANSK and SYSTEM. 


Page 2 The COMAL editor, syntax analysis and code 
generation, prepass (SCAN), recreator (LIST) 
commands. 

Page 3 Runtime-module. 

Page 4 The packages GRAPHICS, TURTLE, SPRITES, FONT, 
SOUND, JOYSTICKS, PADDLES and LIGHTPEN are located 
here. 


EPROM expansion in the cartridge is interpreted as follows, 
depending on EPROM types: 


BKB Page 5, address area #8000-29fff. 
16kKB Page 5, address area $8000-Sbfff. 
32KB Page 5, address area $8000-#bfff, 


Page 6, address area #8000-Sbfff. 


Upon start-up COMAL examines every 4 KB in pages S and 6 to 
find certain bytes which determine if package modules are 
present. Next, signals are sent to the modules, indicating 
that the machine has been turned on. 


MEMORY MANAGEMENT 


The 6510/6502-microprocessor which is used by the Commodore 
64 is not designed to address more than 64 KB. When the 
COMAL cartridge is active, the processor can address up to 
152 KB! A special trick has to be used to achieve this. 
The trick is to determine just what the 6510 should be able 
to "see" in its address space. Memory is partitioned into 
banks (also called pages or overlays). The different banks 
become active as required. The method is termed “bank- 
switching" or “memory management". For example there are 
three banks in the address space S2-S6KB: RAM, 1/0 and 
character set ROM (see memory manager organization). In the 
region 40-48kKB there are actually 8 different banks which 
can be used! 


Banks are selected by writing a bit pattern into certain 


control ports. Two such control ports are available: 

R6510 Controls the C-64 memory map. Located in the 
Commodore, address #0001. Can be written to 
or read. 

OVRLAY Control of cartridge banks. Located in the 


COMAL cartridge at address $de00O in bank I1/0. 
I.e. the port must be accessible when it is 
to be changed. It can only be written to. 


COMAL has system routines, which manipulate these ports. By 
using these routines, one can specify the memory map by 
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simply altering a single byte. The following figure 
specifies several interesting memory maps (i=1,2,..,6): 


RAM RAMCHR RAMTO DEFPAG CBASIC CART i 


KERNEL 


I/O 
RAM 
RAM 


464k. 






ERNEL 


K "2 
RAM 
AM 
: : 
In order for LINK. USE and DISCARD to work, the placement of 


code and the format for package names. procedures and 
procedure headers must be specified. 


KERNEL 


BASIC 










COMAL 
pagei 





Ok 


CREATING MODULES 


If a module is to be placed in RAM, then it must have the 
following format: 


-lib cé4symb 

*=<start address> 

-byte <map> 

eword end 

eword <signal > 

<package table> 

<machine code> 
end eend 


If the module is to be placed in EFROM, ther it must be 
formatted as follows: 


-lib cé4symb 

*=Cstart address> 

word cold 

word warm 

ebyte ‘CBMB0comal ’ 

ebyte > 

»byte <map>+rommed 

-word end 

-word <signal> 

<package table> 

<machine code> 
end end 
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elib cé4symb makes all KERNEL- and COMAL variables known 
to the module. 

<start address> is the starting address for the module in 
memory. 

<map > indicates into which memory map the module 
is to be placed by LINK. This memory map is 
automatically activated by calling a 
procedure, function or signal handler in the 


module. 
rommed indicates that the module cannot be 
DISCARD ‘ed. 
end is the end address of the module + 1. 
<signal > is the signal handler for the module, 


located in <machine code>. 
<package table> is a list of package names. 
<machine code? is all other code in the module. 


A <package table> has the following format: 


ebyte 11, ‘package!’ 
eword procti,initi 
ebyte 12, ‘package2’ 
word proct2,init2 


ebyte O :End of the table 

li is the number of characters in the i‘th 
package name. 

‘packagei ' is the name of the i’th package (in 
quotation marks). 

procti 1s the address of the i’th table of 
procedure names. 

initi is the address of the initialization 


routine for the i’th package. 


A table of procedure names must have the following 
format: 


procti .byte 11, ’proci’ 
word prochi 
-byte 12, ‘proc2’ 
eword proch2 


-byte O sEnd of the table 
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procti 


lj 


‘procj’ 
prochj 


is the 
is the 
is the 
is the 
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address of the i’th table of procedure names. 
number of characters in the j’‘th procedure name. 
name of the j‘th procedure (in quotation marks). 
address of the j‘th procedure header. 


A procedure header has this format: 


type 
codeh 
n 


<parameterk> 


prochj 


funch j 


- byte 
byte 
-byte 
-byte 
byte 


function header 


-byte 
byte 
ebyte 
-byte 
ebyte 


is 
1s 
is 
1s 


proc ,<codeh, >codeh,n 
<parameter 1> 
<parameter2> 


<parametern> 
endprc 


has this formats: 


func+type,<codeh, >codeh,n 
<parameter 1> 
<parameter2> 
<parametern> 
endfnc 
the function type (real, int or str). 
the address of the assembler code routine. 
the number of tormal parameters. 
the specification of the k’th parameter. 


A parameter specification is one of the following: 


-byte 
-byte 


. ebyte 


type 
dim 


real 
int 
str 


byte 


valu 


valuetarrayt+type,dim 
ref+type 
reft+arrayt+type,dim 


1s 
is 


e+type ;Simple value parameter 
sArray value parameter 
;Simple reference parameter 


sArray reference parameter 


the parameter type (reai, int or str). 
the dimension otf an array parameter. 


means the type is REAL. 
means integer type (INTeger). 


means the string type 


(STRing). 


An example of how a procedure header 1s coded: 


FUNC 


pip(x,y#,REF z#(,)) 


ebyte functreal ,<pip, >-pip,s 
valuet+real 
valuetint 
ref+array+str,2 


-byte 
-byte 
-byte 
-byte 


end fnc 


can be coded as 
sKReal func. with 3 param. 
2X 

3;y# 

sREF z#(,) 

;No more parameters 
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PARAMETER PASSING 


When the COMAL interpreter passes control to an assembler 
coded routine, all actual parameters (if any) are computed. 
At the same time parameter types are checked for agreement 
with the procedure header specification. The number of 
parameters in the procedure call must also be correct. 


It is not possible to know in advance where the parameter 
value or the variable (when using REF) are located in 
storage. Therefore it is necessary to call a system routine 
FNDPAR (FiND FARameter) to obtain information about the 
storage address of a parameter. Then the parameter can be 
handled. 


FNDPAR: When called: .A is the number of the parameter. 
On return: COFY1 contains parameter address. 
All registers are changed. 


NB: In the COMAL system the following conventions apply: 
integers and real numbers are stored in high/low format, 
while addresses are saved in low/high format. This is true 
of actual parameters, aiso for parameters of system 
routines. 


In the following the format for each parameter type is 
described: 


VALUE+REAL and REF+REAL 


(COPY1) +0: Exponent+128 
+1: 3 bytes Mantissa(1i) 
2s fioating Mantissa (2) 
+3: point Mantissa(3) 


+4: Mantissa (4) 





VALUE+INT and REF+INT 





(COPY1)+0: High byte 
+1: Low byte 

VALUE+STR and REF+STR 

ms Maximum string length (dimensioned length). 


ns Actual length (If VALUE+STR, then m=n.) 
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(COP Y1)+0: High byte 
Low byte 

+2: High byte 

Low byte 


+4: s$ (1:1) 
s¢(2:2) 
m s$ (3:2) 
bytes s% (4:4) 

+4+n—-1L: s#(nin) (last char.) 
+4+m—1: s3 (m:m) 


VALUE+ARRAY+REAL, VALUE+ARRAY+INT, VALUE+ARRAY+STR, 
REF +ARRAY+REAL, REF+ARRAY+INT, REF+ARRAY+STR 


Every array has an information block: 


n : Number of indices. 
addr: Address of first element in the table. 


(COFY1) +0: Low byte 
High byte 
+25 Number of indices 
£5 Lower Limit High byte 
for 1. index Low byte 
+5: Upper limit High byte 
for 1. index Low byte 
+73 Lower limit High bvte 
for 2. index Low byte 
+9: 
+3+(n-1)#4+2: [Upper limit High byte 


for n‘te ind. Low byte 





+34+ne4s 
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If an array A is declared as: 
DIM a(1:3,6:8) 
it is placed in memory as follows: 


addr+oO : a(1,6) 
+] : a(i,7) 
+2%1:s a(1,8) 
+3*1: alZ,6) 
+4¥#13  a(2,7) 
+5%1: al2,8) 
+6*¥1l:s  al3,6) 
+7*%¥1:3 al3,7) 
+B¥l:s a(3,8) 


where 1 is the size (in bytes) of each array element. 


Each element is organized just as a simple parameter. 


WHERE CAN MODULES BE PLACED? 


Modules can be placed in RAM from $0900-$7ff4 and from 
$8009-Sbf ff. 


In addition packages can be placed in an EFROM in the 
cartridge from $8000-Sbfff, however the start address must 
be a multiple of #1000. 


WHERE CAN THE MODULE VARIABLES BE PLACED? 


Variables which much survive from call to call must be 
placed in the module itself (for RAM-modules). 


EPROM—-module variables can be stored from #c855-#c87a. 


Should more storage be required, and if the RS232 will not 
be used, then the RS232 buffer RSOBUF (256 bytes) can be 
used. If cassette tape will not be used, then the tape 
buffer TBUFFR (192 bytes) can be used. In addition zero- 
page locations #$4c, #56 and #fb-#ff can be used freely. 


Routines which use variables local to the individual call 
can use these local variables: 


Name Address 

INF 1 $0038 

INF2 $0039 

INFS $003a 

Q1 $O003b-S$003c 

Q2 $O002d-S$O003Se 

Q3 S003 -$O0040 

04 $0041-$0042 

Qs $0043-$0044 

COPY1 $0045-4$0046 Also used by FNDPAR 


COPY2 $0047-$0048 
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COPY3 $0049-#0050 

ACI $0061-$0066 Also used by FP-routines 
AC2 £0069-S006f Also used by FP-routines 
MOVEAD $007a-$007b 

TXTLO #007c 

TXTHI #007d 

RANGES $02e0-4£02f f 

TXT $c 760-$c7af 


SIGNAL ROUTINES 


A signal routine is a subroutine which is terminated by an 
RTS instruction. It is permissible for a signal routine to 
do anything which a procedure or a function may do. If a 
signal routine is not required, then a system routine named 
DUMMY can be used. This routine consists of only an RTS 
instruction and does nothing. 


A USE-signal-routine has no parameters. Each time a USE 
<package> statement is encountered in a COMAL program, this 
routine is called. If it is not desired that the package be 
initialized every time, then a variable should be used to 
indicate that a package has previously been activated by 
means of USE. 


A module-signal-routine has one parameter, tor the .y- 
register will contain a vaiue when the cali is executed, 
indicating which type signal is to be transmitted. The 
parameter can be one of the following: 


FOWER1 Is issued at start-up to all ROM’ed modules. 
The signal must be used to initialize the 
module. 

FOWER2 Is issued at start-up after FPOWERI has been 


issued. Ordinarily this signal is ignored, 
but it can be used to allow a module to take 
complete control before COMAL starts. 


LINK Is issued to a just LINK’ed package or to 
those packages which are read in with LOAD, 
RUN <filename>, or CHAIN. With this signal 
the module can change vectors in COMAL and 
the operating system. 


DSCRD Is issued to all modules before DISCARD or 
the NEW command. On this signal the module 
can change vectors back to what they were 
before LINK. 


NEW Is issued with a NEW command. 


CLRTAB Is issued when all names in a program are 
undeclared. This signal is given with the 
RUN and CHAIN commands and in certain other 
cases. When the names are undeclared, then 
it is not possible to call any procedure or 
function in any package. 
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RUN Is issued with the RUN or CHAIN command. 

WARM1 Is issued during “warm start", i.e. when the 
<STQOP-RESTORE> combination is activated from 
the keyboard. 

CON Is issued with the CON command. 


ERROR Is issued after the program has stopped with 
an error message. 


STOF 1 Is issued after a program has stopped due to 
a STOP or END. 


BASIC Is issued before COMAL is exited. 


In general a module-signal-routine follows this outline: 


signal cpy #link 3 LINK~command? 

beq slink s;Jump if so 

cpy #dscerd 3; DISCARD? 

beq sdscrd sJump if so 

rts sIgnore all other signals.; 
slink .. s;LINK—-handler 

rts 3Back to COMAL 
edscrd .. s DISCARD-handler 

rts ;Back to COMAL 


ERROR REPORTING 


It is good programming practice to check whether parameters 
to a procedure or function are legal. It they are not, then 
an error message should be issued. If it is desired that 
COMAL 's own error messages be used, this can be done as 
follows: 


ldx #5 3;Give error number 5 
jmp runerr 3i.e@. "value out of range" 


With this method one can give standard error messages 
numbered 0 to 255. See Appendix F for these error messages. 
RUNERR corresponds closely to the COMAL statement REFORT 
<error> and can be captured in a TRAP structure, if this is 
desirable. 


A more general error reporting method is available. If 
One wants to give the following values to the system or to 


an error handler, 


ERR = 300 
ERRFILE = 0 
ERRTEXT# = “illegal parameter value" 


it can be done with the following routine: 
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text -byte ‘illegal parameter value’ 
textl =#—-text 
3 
err 300 ldx #textl sLength of text 
etx ertlen s:3Length of error message 
errorp Ida text-1,x sMove the text to ERTEXT 
sta ertext-1,x 
dex 


bne errorp 


lda ##é6c sCopy imp (trapvc) to Qi 
sta qi+0 

lda #<trapvc 

sta qi+l 

lda #>trapvc 

sta qi+2 


ldy #0 tERRFILE = O 

ldx #<300 s;sERR = 300 

lda #>300 

jer goto s;Execute jmp (trapvc) in PAGEB 
-byte pageb,<qi,>qi 


PACKAGE EXAMPLE 


The following example shows how a complete module containing 


one package named TEST can be created. The purpose of 
this example is to illustrate how one creates a procedure, 
a real function and a string function. The package is 


placed from address $8009 in RAM in the memory map DEFFAG 
(see the table of useful memory maps shown earlier). 


The package is available on the demo diskette. 


test.arc contains the source code (src=source). 
test.obj contains the object code ‘obj=object). 


In order to get the module with the package test into the 
machine, type: 


LINK "test.obj" 
Next type ins: 


AUTO 

0010 USE test // makes hi, add and string known // 
0020 hi 

0030 PRINT add(23,45) 

0040 PRINT strings ("a",10) 


0050 (Press the <STOP> key.) 
RUN which gives this result: 

hello! 

68 

aaaaaaaaaa 


end at 0040 
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Switch to your own diskette then type: 


SAVE "test" save the COMAL program and the package test. 
DISCARD delete the LINK’ed module. 

RUN run the program again without the package 
test. 


The system will respond with an error message: 
at 0010: test: unknown package 


RUN “test” fetch and run the program with the package 
test. 


New printout: 

hello! 

68 

aaaaaaaaaa 

end at 0040 
Here is the content of the source code of test.grc: 
—--=== package test===--- 


make all symbols known: 


‘98 ‘28 28 a8 


»lib cé4symb 


-opt list slast this module 

| x=$8009 sstart address 

. -byte defpag :52KB RAM memory map 
-word end sthe module ends with end 
-word dummy sno signal handler 


package table: 


‘oo ‘ae ge 


-byte 4, test’ sthe package is called test 
-word testp sprocedure table 

-word dummy sno initialization 

-byte O :no more packages 


procedure table: 


rh 20 #0 ‘a0 


estp .byte 2, ‘hi’ sthe procedure hi 
-word phi sProcedure header for hi 
-byte 3, add’ sthe function add 
-word padd 
-byte 6,’string’ 3s;function string 
-word pstrin 
-byte oO sno more procedures 

: proc hi 

phi -byte proc,<hi,  >hi,O sno parameters 


sbegins in hi 
-byte endprc 
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: func add la#t,b#) 
3 
padd -byte functreal ,<add,>add,2 ;two parameters 
sbegins in add 
-byte valuetint :;a# is integer value parameter 
-byte valuetint s:b# is integer value parameter 


-byte endfnc 


func string# (characters ,number #) 


UD om as ve 


strin .byte func+t+str ,<string, sstring,2 s;two parameters 
sbegins in string 
-byte valuetstr scharacter? is string value parameter 
-byte valuetint snumber# is integer value parameter 
ebyte endtfnc 


proc hi 
print "hello!" 
endproc hi 


text -byte ‘hello!’ ,13 stext to be printed 
textil =*-text slength of text 
3 
hi ldy #0 sbegin with 1. character 
hilp Ida text,y sfetch character 
jsr cwrt sprint character on screen 
iny snext character 
cpy #textl s;finished? 
bne hilp sjump if not finished 
rts sreturn to COMAL 


func add (a#,b#) 
return a#+b# 
endfunc add 


ny) ‘a0 ‘ae we ‘ee ‘an 88 


dd lda #1 ;get address of 1. Darameter 
jsr fndpar scopyl = address 
ldx copyl smove address to copy2 
lda copyl1+1 
stx copy2 


sta copy2+tl 


lda #2 sget address of 2. parameter 
jsr fndpar 


copyl points now to b# and copy2 points now to at 


a0 #206 ‘#@ 


Idy #1 sNB: integers are in high/low format 
clc sno carry 

Ilda (copy2),y slow byte of at 

adc (copyl),y s;plus low byte of b# 

tax 3;-a is moved over to .x 

dey s-y:=0 

lda (copy2) ,y shigh byte of aft 

adc (copy!) ,y sPlus high byte of b# plus carry 

bys ovrflw jump if arithmetic overflow 


-x = low byte of a#+b# 
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-a = high byte of a#+b# 


convert from integer to real number; 
then put result on COMAL’s stack. 


ae we we we we 


jsr pshint sconvert and push. 

rts sreturn to COMAL with the result 
ovrflw ldx #2 s "overflow" 

jmp runerr sreport 2 


func string#(character#,length#) closed 
if length#<0O then report 1 // argument error // 
if len(character#)<>1 then report 1 // argument error // 
dim r¥ of length# // room for result // 
for i#=1 to length# do // generate result // 
r#:+characters 
endfor i# 
return r$ // return result // 
endfunc string 


= | me ‘a8 ‘60 ‘48 e068 ‘#8 ‘ee ee ‘40 we we ‘se 


um =copy2 suse copy2 as num 
string lda #2 sqget address of 2. parameter 
jsr fndpar 
ldy #0 stest sign 
lda (copvil),v 
bmi argerr sjump, if <O 
sta numt+i shigh byte of num 
iny s:.y:=1 
lda (copyl),y 
sta num slow byte of num 


generate the result directly on COMAL’s evaluation stack. 


stos points to the next free byte on the stack 
the stack is limited upwards by sfree 
test if there is room for the result 


cle sclear the carry 

adc stos snum+stos 

tax :.x:=low byte of num+stos 
lda num+1 

adc stos+i seazs=high byte of num+stos 
bes sterr sjump, if overflow 

tay 

txa snum+stos+2 

adc #<2 sthe carry is known to be = 9 
tax 

tya 

adc #>2 

bes sterr sjump, if overflow 

cpx sfree sif num+stos+2>=sfree, 

sbc sfreetl sthen stack-—-over flow 

bcs sterr sjump, if stack-overflow 


check characters. 
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‘ae ‘ae 0 


strip 


set 


20 #6 ‘46 


strok 


$ 
argerr 


sterr 


lda 
jsr 
ldy 
lda 
bne 
iny 
lda 
cmp 
bne 


iny 
lda 


ldy 
sty 
sty 


ldx 
cpx 
bne 
ldx 
cpx 
beg 


sta 


inc 
bne 
inc 


inc 
bne 
inc 
Jmp 


the 


lda 
sta 
iny 
lda 
sta 


cle 
lda 
adc 
sta 
lda 


adc 


sta 
rts 
1dx 
jmp 
ldx 
jJmp 


#1 
#ndpar 
#2 


(copyl),y 
argerr 


(copyl),y 
#1 


argerr 


fetch character$(1:1) 


(copyl),y 


write character (1:1) 


#0 


qi 
git+l 


num+ 1 
gi+l 
stri 
num 
ql 
strok 


(stos) ,y 


stos 
str2 
stos+l 


qi 
strip 
qi+l 
strip 


length of the 


num+ tl 
(stos),y 


num 
(stos) .y 


stos 
#<2 
stos 
stos+i 
#>2 
stos+i 


#1 
runerr 


#56 
runerr 
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sget the address of character? 


scurrent length must = i 
shigh byte must = O 


seyr=3 
slow byte must = 1 


s-az=characterg#(1:1) 


num times on the stack. 
:qi:=0 // loop variable 


swhile qi<>num do 


: rs(qizqi):=character#(1:1) 


s tos:+1 


; qi:+l 


sendwhile 

string to num. 

s;save high byte of the length 
:-y:=1 


ssave low byte of the length 


sstos:+2 // room for the length // 


sreturn to COMAL with the result 


:"argument error" 


s"out of memory" 
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end -end send of source text 
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COMMODORE 644 Character Codes 


ASCII CHARACTERS SCREEN CHARACTERS 
mode mode 
CODE text graphics text graphics 


< STOP > 


white 


<SHIFT - C=)> disable 
<SHIFT - C=> enable 

clear to end of line 
form feed (printer) 

< RE TURN> 

Switch to lower case 


ODVNHUDAHW MRO 
—- Few FO AMAN THEA 


“* 38 


cursor down 
reverse on 
cursor hore 
<DEL > 


spy VT 0 


red 

cursor right 
green 

blue 

space 


ec 
A 
B 
Cc 
BD 
E 
F 
G 
H 
I 
J 
K 
L 
M 
N 
a) 
e 
Q 
R 
S 
+ 
U 
Vv 
W 
* 
Y 
Z 
f 
D 
A 
ft 
e 


-4)? @ MR NX XR E ¢ C Aw 
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CHARACTER CODES 


Appendix A - 


SCREEN CHARACTERS 


ASCII CHARACTERS 


mode 


mode 


graphics text graphics 


text 


CODE 


or NOT wW ore OM « 


O- NMOTMNOKAM 


o-UMT NOR GDM 


oaono- uns Nor D 
T,r7TNnNNNNN NNN NH 


svt nae b@— tbl bteamer nan JYNLGF O@ le -—- SKOK~O tm — oP 


eav INO AeeEOaoauwoerenwv it FEZoOacetenriarsr>axkKrnwtaced 


NHOROMROmNMTNHROMO-NUNM 
KKRAR RR OWOODDDDODOHHAHnD 


ey Ae | TCMovOAuUHLOTKXHOYIEZOVCSCKHrFDDRAPBX¥YNH ACHES a Fl 


le— | 
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ASCII CHARACTERS SCREEN CHARACTERS 
mode mode 
CODE text graphics text graphics 


E 
F 
G 
H 
I 
J 
K 
L. 
M 
N 
0 
P 
Q 
R 
Ss 
T 
U 
Vv 
LJ 
x 
Y 
Z 
ft 
@ 
A 

% 
Ss 


orange Codee 128-255 are 
reversed images of 
< RUN> codes Q-127 


#1 

#3 

#35 

#7 

f2 

#4 

#& 

#8 

< SHIFT-RE TURN? 
switch to upper caze. 


black 

cursor up 

reverse off 

as <CLR> (clear screen) 
as < INST) C insert) 
brown 

light red 

dark grey 

grey 

light green 
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ASCII CHARACTERS ASCII CHARACTERS 
mode mode 
CODE text graphics CODE text graphics 


light blue 
light grey 
purple 
cursor left 
yellow 

cyan 

space 


ZsgeraamaAn«x xXxeccHdnnoadv9dsaZ 


re TT ws 
= 


alia Ce a Sea a 
bo 4s ba 8 
_4 7 


” 
ax me 
%, 
\ i 
t t 
8 a 
t L 


‘8 
4 


an 1 ert 4 


ee or ee 


ZTAGUeHnTOANAMIOODWD! Ff w#Ae 
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COLOR CODES 


Color Color Grey ASCII Keyboard 
code scale value 
O black 4/4 144 <CTRL-1 > 
1 white 0/4 3 <CTRL-2> 
2 red 3/4 28 <CTRL-S3? 
= cyan 1/4 159 <CTRL-47 
4 purple 2/4 156 <CTRL-S> 
va green 2/4 20 <CTRL-G> 
6 blue a/4 = <CTRL-7 > 
7 yellow 1/4 158 <CTRL-8> 
8 orange 2/4 129 <C= 12 
9 brown 3/4 149 <C= 22 
10 pink 2/4 150 <C= 3> 
11 dark grey 3/4 151 <C= 47 
12 grey 2/4 152 <C= Ss 
13 light green 1/4 153 <C= 62 
14 light blue 2/4 154 <C= 7> 
15 light grey 1/4 155 <C= 8> 


COLOR COMBINATIONS ON THE TV/MONITORs 
(from the Commodore 64-Programmer’s Reference Guide) 


How do the colors go together”? 


+ 
Oo 


very well 
well 
poorly 


screen text color code 
color 
code, O 68 910111213 14 


+ 


0o+0 + + + 


0 
1 
2 
3 
4 
» 
& 
7 
8 
9 


+++++%+0 
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Appendix Cc — 
CALCULATIONGS WITH Comal 


The COMAL operating system can handle 4 types of numerical 
constants and variables: 


real numbers E.g. 3.232 , 4.6e-12 , FI, a , Sum 
integers 71 , —-3067, nr# , item# 
hexadecimal numbers #la , $d7 , #acOO0 , no , position 
binary numbers “Z%41011 , 4190011010 , byte , id 


NUMBER RANGES: 


2.973872588e-39 <= real number <= 1.70141182e+38 

—-32768 <= integer <= 32767 

Oo = $00 <= hexadecimal <= #ffFff = 65535 

Oo = ZO {<= binary number <= 4£1111111111111111 = 65535 


CALCULATIONS ARE CARRIED OUT ACCORDING TO THE FOLLOWING RULES: 


An expression to be evaluated may contain a mix of all 
number types and number variables. It may contain a mix of 
arithmetic operators, relational operators and boolean 
operators. Standard COMAL functions and user defined 
functions can also be included: 


* an expression is evaluated from left to right, 
* however, various operators have different priority. 
The calculations are carried out according to the 


following priority, highest priority first: 


PRIORITY: 
(in order of highest priority) 


1. parenteses 


Arithmetic operators: 


a exponentiation 22 equals 8 

sc. * multiplication 2*S equals 6 

Oe a division 7/2 equals 3.5 

o>. DIV integer division 24 DIV 8 equals & 
>. MOD remainder after division 22 MOD 7 equals 2 
4. + addition 2+3 equals 5 

4.- subtraction 4-3 equals 1 

4. - monadic subtraction -S+2 equals —-3 


Logical operators for bitwise comparisons: 
(See further explanations in the reference section, 
Chapter 4.): 


9. BITAND bitwise logical ‘and’ 
4. BITOR bitwise logical ‘or’ 
3. BITXOR bitwise logical ‘exclusive or’ 
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Relational operators: 

(Comparisons occur in logical expressions, which can be 
TRUE (=1), if the comparison is true. Otherwise the 
logical expression has the value FALSE (=0)). 


6. < less than S*¥269 equals TRUE 

6. <= less than or equal to 4*#3<=10 equals FALSE 
6. = equal to 1=2 equals FALSE 

6. >= greater than or equal to 17>3 equals TRUE 

&. > greater than 7>7 equals FALSE 

6. <> not equal to S¥24 76.01 equals TRUE 


Boolean (logical) operators: 
(See further explanation of the individual words in 


Chapter 4.): ® 


7. NOT logical negation 
8. AND logical ‘and’ 

8. AND THEN as AND 

9. OR logical ‘or’ 


9. GR ELSE as OR 


STANDARD FUNCTIONS: 


INT (x) Integer part of x INT(3.2) equals 3 

ABS (x) Numerical value of x ABS(-2.5) equals 2.5 
SGN (x } Sign of x SGN(-3) equals —-i 
SIN(x) Sine of x SIN(PI/46) equals O.5 
COS (x) Cosine of x COS(FI) equals -i 

TAN (x ) Tangent of x TAN(PI/4) equals 1 
ATNix) Inverse tangent of x ATN(1) equals FI/4 
LOG (x) Natural logarithm LOG(10) equals 2.3026 
EXF (x) Exponential function EXF (2) equals 7.389 
SOR (x ) Square root of x SQR(9) equals 3 


EXAMPLES OF USER DEFINED FUNCTIONS: 


FUNC asin (x) 
IF ABS(X)=1 THEN 
RETURN X*¥PI/2 
ELSE 
RETURN ATN(x/SQRC1—-x*x) ) 
ENDIF 
ENDFUNC asin 





FUNC log1O0(x) 
RETURN LOG(x)/LOG(10) 
ENDFUNC 1l1og10 
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KEYBOARD AND SCREEN EDITOR 


THE ACTION OF SPECIAL KEYS IN COMALs 


<-> 
Underlining 


<CTRL> 
has special meaning when used with other keys. See the 
following. 


<RUN/STOP > 
interrupts program execution. 
Action is affected by the COMAL statement ESC. See Chapter 4. 


<SHIFT/LOCK> 
locks xSHIFT? in upper case mode. 
Release by pressing the key again. 


<SHIFT> 

As on a typewriter. If this key is held down while another 
key is pressed, an upper case character 1S produced. Letters 
appear as upper case. In the semigraphics mode the symbols 
on the right front side of the keys are produced. «<SHIFT> 
pressed together with other special keys has other functions 
as described with these keys. 


<C=> THE COMMODORE KEY: 


<C= SHIFT> 
Each activation toggles the screen display between lower and 
upper case. 


<C= number > 
Pressing the C= key with a number 1-8 switches to colors 
with color codes 8-15. 


<C= graphics symbol > 
Pressing a key with graphics symbols equals the symbol shown 
on the front left of the key. 


<CLR/HOME > 
moves the cursor to the upper left corner of the screen. 


<SHIFT-CLR/HOME> 
clears the screen. 


<INST/DEL> 

is the delete key. It deletes the character immediately to 
the left of the cursor, and the remainder of the line moves 
one space to fill in the gap. 


<SHIFT-INST/DEL> 
is the insert key. It pushes the character under the cursor 
and the rest of the line one space to the right. 
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<STOP—RES TORE > 

If the <STOP> and <RESTORE> keys are pressed at the same 
time, the computer is ‘reset’. The program in working 
memory is not lost. 


<RETURN> 
Indicates that all information on the current line should be 
interpreted and processed. 


<CRSR> 

There are two keys which are used to move the cursor around 
the screen. The arrows indicate directions. Fach key has 
two functions. The function changes when the «SHIFT? key is 
depressed. 


THE FUNCTION KEYS (<#1> - <#8>) 


The function keys can be programmed by the user to perform 
various functions. (See further details in Chapter 5 in the 
section dealing with the procedure defkey in the COMAL 
package system.) 


When COMAL is started up, these keys have the following 
functions: 


<#1> RENUM + <RETURN? 

<#2> MOUNT + <RETURN?> 

<#3> USE turtle + <<RETURN? 

<f4> AUTO 

<¥#35> EDIT 

<#6> LIST 

<#7> RUN + <RETURN? + CHR#(11) + <RETURN?> 


se me me ee re cs re re ee me we a te ae ee ce ee ee we re ee es ee ee we ee ee ee ee + 


Note on <#7>8: In addition to ordinary running of 

a program, this key can be used to start a program 
directly from the disk catalogue. RUN, RETURN 
would have the effect of running the program with 
the name which follows on the same line. However 
the text prg also appears after the program name 
when the catalogue is displayed, so the system @ 
reacts with an error message, placing the cursor 
just ahead of the ‘error’ prg. Then ASCII-code 

11 deletes the rest of the line. Now the line is 
correct, and the program can be run when the last 
RETURN is activated. 


en ee re cere ce te ce ec rm ee ee cr ee cre re ee ee re ee em ee res me rm re re ce ee ce ee ree ee ee we ee es ee 


<#8> SCAN + <RETURN> 


During program execution the function keys have other 
values: ASCII values 133 - 140. 


After execution of one of the orders USE graphics or USE 
turtle the function keys <#1>, <f3> and <f§> have the 
following meaning: 


<#1> textscreen (show the text screen) 
<#3> splitscreen (show graphics screen with 4 lines of text) 
<f#5> graphicscreen (show the graphics screen) 
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THE CONTROL KEY <CTRL>s 


<CTRL—-number > 


<CTRL> together with a number 1 


- 8 causes subsequent text 


to be written with the color indicated on the front of the 


number key. 


text. 


<CTRL> together with 9 or O toggles inverse 


See also Appendix KE on colors and Chapter 5 on the procedure 
quote ’mode in the COMAL package system. 


DURING EDITING OF COMAL PROGRAMS THE FOLLOWING CTRL- 
FUNCTIONS ARE USEFUL: 


<CTRL> + <letter> 


<CTRL-A>: 


<CTRL-B>: 
<CTRL-C>s: 


<CTRL-D>: 


<CTRL-E>: 
<CTRL-F >: 


<CTRL—-K>: 


<CTRL-L>s 


<CTRL—M>1 


<CTRL—-P >: 


<CTRL-&S>s3 


<CTRL-U>s 


<CTRL-V>: 


Is used during the correction of a program line 
which extends over more than one line on the 
screen. If the first 1 to 4 characters in the 
linie in which the cursor is located is a line 
number, then the line number will be rewritten 
with no gaps. <CTRL-A> can also be used as an 
OOFS'-key: If a correction has been made, and 
RETURN? has not yet been pressed, then pressing 
<CTRL-A> will cause the line to be printed again 
in its original form. 


moves the cursor back one word. 

corresponds to <STOF>. 

dumps the graphics page to the printer. The 
printout begins 13 characters from the edge of the 
paper. This order can only be used with Commodore 
MFS801 compatible matrix printers. 

changes the cursor color to white. 


moves the cursor forward one word. 


deletes all characters from the cursor position 
to the end of the line. 


moves the cursor to just after the last non- 
blank character on the line. 


corresponds to <RETURN>. 


prints out 
The printout 


Executes a hardcopy("lps"). I.e. 
the text screen to the printer. 
begins with a carriage return. 


corresponds to <CLR/HOME>. 


<f1>, 
of the 


removes the graphics mode functions for 
<f3> og <f5>. See also the description 
function keys. 


sets up the color choice textcolors(6,6,1). 


AppenDIXx D - 


<CTRL—-W>s 


<CTRL-X>3 


<CTRL-Y>: 


<CTRL-Z>: 
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This corresponds to a blue edge, blue background 
and subsequent white text. This is a good choice 
for a color display. Note that the current text 
screen 1s cleared by this order. 


sets up the color choice as 

textcolors#(11,15,0). This corresponds to a dark 
grey border, light grey background and subsequent 
black text. This order clears the text screen. 
It is a good choice when using a black/white 
display. 


changes the border color... It is followed by a 
color choice: <CTRL number> or <C= number >. 


changes the background color... It 1s followed 
by a color choice: <CTRL number? or <C= number>. 


The selected combination of border, screen and 
text colors are stored and will be reset when 
<STOP-RESTORE? is executed. 
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HANDLING TEXT WITH coOmMaAL 


Text variables (also called ‘strings’ or ‘string 

variables’) are specified in COMAL by means of a sequence of 
up to 80 characters followed by a # sign. The first 
character must always be a letter, and certain special 
characters may not be included in the name. 


Examples: name#, text#, from?, long’namet. 


Before a text variable can be used, it must be declared 
(dimensioned). The system must be provided with information 
on the maximum number of characters the text variable will 
contain, so that room can be reserved in memory. This 1s 
done using the DIM statement: 


Examples: DIM text# OF 80 
DIM name# OF 20 
DIM answer? OF 1 


A text variable can contain any character sequence up to the 


dimensioned length. (Exception: the character " may not be 
used alone. If this character is to be included, you must 
use "" to indicate it. If a number is enclosed within the 


"", then the corresponding ASCII code will be part of the 
text variable assignment.) 


If a text variable is not dimensioned, then the first 
assignment instruction will automatically execute: DIM 
names OF 40. If a variable name is not dimensioned, and 

the name is used before an assignment has been made, then an 
error message will be generated. 


EXAMPLES OF TEXT VARIABLE USAGE: 


Make the assignments: slogan$:="comal is ok" 
textS:="a flower is beautiful”. 


The text can be analyzed with the aid of standard functions 
and operators. 


lengths =LEN (sl ogan$) length is assigned the value 
11, for slogans consists of il 
characters. See a detailed 
description of the function LEN in 
Chapter 4. 


position:="mal" IN slogans position is assigned the 
value 3, since the text 
"mal" is contained in 
slogans, and the first 
character in "mal" is the 3. 
character in slogans. See 
the more detailed description 
of the operator IN in Chapter 
4. 
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ascii: =ORD (texts) ascii is assigned the Commodore 
ASCII value for the letter a (= 6&5). 
See the ASCII values for all characters 
in Appendix A. 


text$<slogans the logical expression will be true 


(TRUE = 1), because a precedes c in 
the alphabet. 


SELECTION OF STRING SEGMENTS: 


letters: =text$ (6) letter$ is assigned the string "r", 

or which is the 8. character in text$ 

letters: text (8:8) 

first$:=slogan$(3:5) firsts is assigned the string 
"“comal”, i.e. the 5 first characters in 
slogans. 

Llast$:=text$(133) last$ is assigned the text 

or "beautiful", i.e. the last 


Llast$:=text$ (LEN (text) —-B: ) nine characters in text$. 


t$: slogans (3:8) t$ is assigned the string 
“mal is". 
t$:=2"programs" (317) is assigned the string ram. 
t$3 =STRS (1789) (2:3) t$ is assigned the string "78". 
t$zs=(text$(4:9)) (234) t$ is assigned the string 


"owe", which is part of 
a part of a string. 


text$(3:8):="bee" text$ will equal 
a bee is beautiful after 
this instruction has been 
executed. 


SELECTION OF TEXT SEGMENTS FROM INDEXED STRING VARIABLES: 


DIM name#(3) OF 20 
name#(1):="Adam Smith" 
name# (2):="Eva Smith" 
name? (3) :="Krystle Smith" 


t$: =name$ (2) (115) t$ is assigned the string "Eva §S". 


DIM item$(3,2) OF 10 
item#(1,1):="book" 
item$ (1,2) :="magazine" 
item$(2,1):s="car" 
item# (2,2) :="train" 
item$ (3,1) :2="oil1" 
item$ (3,2) :="gas" 


selectS:=item#(2,1) (2:3) select$ is assigned the string "ar". 
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CONCATENATION OF STRINGS: 
Pplace$:="VYankee"+" stadium" strings can be linked 


together using the 
character +¢. 


messages: =slogans+" and easy" messages is assigned the 
string “comal is ok and easy". 


helloss: =name$ (2) (:3)+text$(93)+" and "+slogan$(10:11) 
hello# is assigned the string "Eva is beautiful and ok". 
t$:=("we and "+slogan$(i:5))(4:8) t$ is assigned the 
string "and c". 
STRING FUNCTIONS: 


The user can define string functions at will to produce string 
segments: 


0010 FUNC upper$(lowers) 
0020 FOR i#:2#1 TO LEN(lowers$) DO 


0030 a: =ORD (1 ower $ (i #) ) 
0040 IF a>64 AND a<94 THEN 
0050 az+128 

0060 lower $ (i#) 3s =CHRS (a) 
0070 ENDIF 


0080 ENDFOR i*# 

0090 RETURN lowers 

0100 ENDFUNC uppers . 

Examples of the use of the function uppers: 

PRINT upper$("merry christmas") yields the printout: 
MERRY CHRISTMAS 

PRINT uppers ("headline:") (428) gives the printout: 
DLINE 

Using COMAL it is easy to define the Basic-function mid$: 

0010 FUNC mid$(as,start,number ) 

0020 RETURN a$(starts:start+number-1) 

0030 ENDFUNC mids 


This function can be used in lieu of mid#, if you wish to use 
parts of existing Basic programs. 
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COMAL ERROR NUMBERS AND MESSAGES 


The standard version of Commodore 64 COMAL contains error 

messages in two languages. When the computer 1s turned on 

with the COMAL cartridge in place, English error messages 

will be in effect. If desired Danish error messages can be 
selected by means of the order: 


USE dansk 


To get back to English, execute: 
USE english 


After issuing one of these orders, all subsequent error 
messages will be printed in the language you have chosen. 
However, error messages for the disk operating system will 
always be in English. 


It 1s of course possible to incorporate error messages in 
other languages into a COMAL cartridge. Contact your 
Commodore national distribution center for further 
information. 


The COMAL system can give error messages in the following 
situations: 


* When typing in an instruction line 
* When examining program structure (using scan) 
* During a run (run-time errors) 


The remainder of this Appendix includes a list of all error 
messages and their corresponding numerical code. Note that 
the list is given both in English and in Danish for those of 
you who may be curious about the strange language which 
COMAL can use: 


DYNAMIC SYNTAX ERROR MESSAGES: 


<language element> ikke forventet 
<language element? not expectet 


<language element> mangler 
<language element> missing 


<language element 1> forventet, ikke <language element 2> 
<langquage element 1> expected, not <language element 2> 


DYNAMIC STRUCTURE ERROR MESSAGES (PREPASS) s 


<statement 1> uden <statement 2> 
<statement 1> without <statement 2> 


<statement> mangler 
<statement> missing 
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ikke <statement 2> 
not <statement 2> 


<statement 1> forventet, 
<statement 1> expected, 


<statement> ikke tilladt i styrestrukturer 
<statement> not allowed in control structures 


import kun tilladt 1 lukket proc/func 


ERROR MESSAGES 


import allowed in closed proc/func only 


forkert 


slags <statement> 


wrong type of <statement> 


forkert 


NMavn 1 <statement > 


wrong name in <statement> 


ulovlig 
illegal 


DYNAMIC 


<name>: 
<name>: 


<name?: 
<name>: 


<name>: 
<name>s 


<name>: 
<name>s 


<name>: 
<name>s 


<name>: 
<name>: 


<name>: 
<name>: 


<name>: 
<name>: 


<name>: 
<name>s 


<name>: 
<name>: 


<name>: 


navn allerede defineret 
name already defined 


ukendt etikette 
unknown label 


goto 
goto 


RUN TIME ERROR MESSAGES: 


ukendt statement eller procedure 
unknown statement or procedure 


ikke en procedure 
not a procedure 


ukendt variabel 
unknown variable 


forkert type 
wrong type 


forkert funktionstype 
wrong function type 


hverken tabel eller funktion 
not an array nor a function 


ikke en simpel variabel 
not a simpel variable 


ukendt tabel eller funktion 
unknown array or function 


forkert tabeltype 
wrong array type 


import fejl 
import error 


ukendt pakke 
unknown package 


navn redefineret 
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<name>: array redefined 


<name>: navn allerede defineret 
<name>: name already defined 


<name>: tekstvariabel ikke defineret 
<name>: string not dimensioned 


<name>: ikke en pakke 
<name>: not a package 


RUN 


Oo 


tA 


un 


10 


11 


13 


14 


1S 


16 


17 


TIME ERROR, WHICH CAN BE TRAP ’PED: 


report fejl 
report error 


argument fejl 
argument error 


over loeb 
overflow 


division med nul 
division by zero 


delstrengsfejl 
substring error 


uden for vaerdiomraade 
value out of range 

step = 0 
step = O 


ulovlige graenser 
illegal bound 


#ejl i print using 
error in print using 
ulovlig indexvaerdi 


index out of range 


ulovligt filnavn 
invalid file name 


verify fejl 
verify error 


program for stort 
program too big 


daarlig comal kode 
bad comal code 


ikke comalprogramfil 
not comal program file 


program lavet t11 anden comalversion 
program made for other comal version 


ERROR MESSAGES 
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350 


(+ 
i 


CA 
tl 


Cf 
Ch 


27 


98 


39 


60 


61 


62 


ulovlig farve 
illegal color 


ulovlig graense 
illegal boundary 


ulovlig tegning-nummer 
1llegal shape number 


tegningens laengde skal vaere 644 
shape length must be 64 


ulovlig sprite-nummer 
illegal sprite number 


ulovlig stemme 
illegal voice 


ulovlig node 
illegal note 
TIME ERROR, WHICH CANNOT BE TRAP ’PED: 


system fejl 
system error 


for lLidt hukommelse 
out of memory 


forkert dimension i parameter 
wrong dimension in parameter 


parameter skal vaere en tabel 
parameter must be an array 


for faa indices 
too few indices 


strengtildelingsfejl 
string assignment error 


ikke implementeret 
not implemented 


con ikke mulig 
con not possible 


Pprogrammet er blevet modificeret 
Program has been modified 


for mange indices 
too many indices 


funktionsvaerdi ikke returneret 
function value not returned 


ikke en variabel 
not a variable 


ERROR MESSAGES 
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67 parameterlister afviger eller ikke lukket 
parameter lists differ or not closed 


68 ingen lukket proc/func i fil 
no closed proc/func in file 


69 for faa parametre 
too few parameters 


790 forkert indextype 
wrong index type 


71 parameter skal vaere en variabel 
Parameter must be a variable 


72 forkert parametertype 
wrong parameter type 


73 ikke-ram indlaesning 
non-ram load 


74 checksumfejl 1 objektfil 
checksum error in object file 


73 hukommelsesomraade beskyttet 
memory area is protected 


76 for mange biblioteker 
too many libraries 


77 ikke en objektfil 
not an object file 


78 ingen passende when 
no matching when 


79 for mange parametre 
too many parameters 
SYNTAX ERROR: 


101 syntaksfejl 
syntax error 


102 forkert type 
wrong type 


103 saetning for lang eller for kompliceret 
statement too long or too complicated 


104 kun som saetning, ikke som kommando 
statement only, not command 


106 linienumre er fra 1 til 9999 
line number range: 1 ta 9999 


108 procedure/funktion findes ikke 
procedure/function does not exist 


109 struktureret saetning ikke tilladt her 
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111 


112 


113 


114 


115 


-2%- ERROR MESSAGES 


structured statement not allowed here 


ikke en saetning 
not a statement 


linienumre vil overskride 


9999 


line numbers will exceed 9999 


kilde beskyttet!!! 
source protected!!! 


ulovligt tegn 
illegal character 


fejl 1 konstant 
error in constant 


fejl i eksponent 
error in exponent 


INPUT/OUTPUT- ERROR MESSAGES, 


200 


201 


206 


207 


208 


209 


210 


211 


212 


ikke flere datalinier 
end of data 


slut paa fil 
end of file 


fil allerede aaben 
file already open 


fil ikke aaben 
file not open 


ikke en inputfil 
not input file 


ikke en outputfil 
not output file 


WHICH CAN ALL BE TRAP ’PEDs 


numerisk konstant forventet 


numeric constant expected 


ikke en random access fil 
not random access file 


enhed ikke tilstede 
device not present 


for mange filer aabne 
too many files open 


laesefe jl 
read error 


skrivefejl 
write error 


kort blok paa baand 
short block on tape 
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213 


214 


2i5 


216 


217 


218 


219 


lang blok paa baand 
long block on tape 


checksumfejl paa baand 
checksum error on tape 


slut paa baand 
end of tape 


fil ikke fundet 
file not found 


ukendt enhed 
unknown device 


ulovlig operation 
illegal operation 


i/o afbrydelse 
1/o break 


MESSAGES FROM THE DISK OPERATING SYSTEM (ONLY IN ENGLISH): 


220 


221 


222 


252 


2335 


2354 


250 


21 


202 


read error (Block header not found) 

read error (Synchronization mark missing) 

read error (The data block is not present.) 

read error (Checksum error in the data block) 

read error (Error in byte decoding) 

write error (Write/read error) 

write protect on (The diskette is write protected.) 
read error (Checksum error in the header) 

write error (Long data block) 

disk id mismatch (UnMOUNTED or nonmatching diskette) 
syntax error (Ordinary syntax error) 

syntax error (Incorrect DOS-command) 

syntax error (Line too long) 

syntax error (Incorrect file name) 

syntax error (No file was indicated) 

syntax error (Incorrect pass-command) 

record not present (Reading beyond the last record) 
overflow in record (Record length overrun) 


file too large (‘No room for the random file) 
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260 


261 


262 


write file open (An already opened file opened again) 
file not open (Tried to access an unopened file) 

file not found (The file does not exist in the disk drive) 
file exists (The file is already present on the disk.) 
file type mismatch (Operation on files of different type) 
no block (The block is reserved.) 

illegal track and sector (Track/sector does not exist.) 
illegal system t or s (Illegal system track or sector) 

no channel (There is no available channel.) 

dir error (Directory error) 

disk full (The diskette is filled up.) 

cbm dos vx.x yyyy (Diskette status) 


drive not ready (No diskette) 
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USER COMMENTS AND CORRECT IONGS 


These pages are intended to be used for your comments and 
corrections. When sufficient experience with the use of 
this handbook has been acquired, it will be reprinted. It 
will be advantageous to all users that errors are corrected 
and improvements are made for the next edition. Send your 
comments tos 


COMMODORE DATA A/S 

ATT: Jan Nymand 
Bjerrevej 67 

DK-8700 Horsens, DENMARK 


Thanks for your help! 
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SAamMmrLwe ComMmMALKX FROGRAMS 


0010 
0020 
0030 
0040 
0050 
0060 
0070 
0080 
0090 
0100 
0110 
0120 
0130 
0140 
0150 
0160 
0170 
0180 
0190 
0200 
0210 
0220 
0230 
0240 
0250 
0260 
0270 
0280 


* 0290 


0300 
0310 
0320 


0010 
0020 
0030 
0040 
0050 
0060 
0070 
0080 
0090 
0100 
0110 
0120 
0130 
0140 
0150 
0160 
0170 
0180 
0190 
0200 


// save “@Music 1" 
DIM code¢ OF 3S 


USE sound 

LOOP 
PAGE 
PRINT “Choose voice (1,2 or 3)" 
PRINT “Choose note (a2,c4,b3,...)" 
PRINT “The numbers = octave:" 
PRINT “‘c4’ is middle C (4. octave - 440 Hz)" 
PRINT ““45#'° is) ’# sharp’ in the octave above" 
PRINT AT 22,1: "LESSON 1: We play a single note..." 
PRINT AT 20,1: "(Press <RUN/STOF? to end ...)" 
PRINT 
INPUT AT 8,1: “voice: ": voice 
INPUT AT 9,1: "note-code: ": code? 
Play (1,code#) 

ENDLOOP 

PROC play (voice,code?) 


IF code#<>"z" THEN 
note (voice ,code#) 
gate(voice,1) // attack and decay 
ENDIF 
pause(14) // sustain 
gate(voice,9) // release 
ENDPROC play 


PROC pause (sec ‘22) 

TIME O 

WHILE TIME<1.875*sec ’32 DQ NULL 
ENDPROC pause 


// save "@Music 2" 
DIM codes OF 3 


USE sound 
LOOP 
PAGE 
PRINT “Type in a note (a2,b5,c4,...)" 
PRINT "The 3 voices are played in succession." 
PRINT AT 22,1: "LESSON 2: 3 voices are played..." 
PRINT AT 20,1: “Press <RUN/STOP> to end..." 
PRINT 
FOR voice:=1 TO 3 DO 
soundtype(voice,3) 
ENDFOR voice 
INPUT AT 7,1: “note-code: ": code 
FOR voice:=1 TO 3 DO 
PRINT AT 10,1: “voice "s3voice 
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0210 
0220 
0230 
0240 
0250 
0260 
0270 
0280 
0290 
300 
O310 
0220 
02330 
340 
0350 
0360 
0270 
0380 
9390 


0010 
0020 
0030 
0040 
0050 
0040 
0070 
Q08O 
0090 
0100 
O110 
0120 
0120 
0140 
0150 
0160 
0170 
0180 
0190 
0200 
0210 
0220 
O230 
0240 
0250 
0260 
0270 
0280 
0290 
0300 
O310 
0320 
0320 
0340 
0350 
0360 
0370 
0380 
0390 
0400 


play (voice,code$) 
play (voice,"2") 
ENDFOR voice 


ENDLOOP 


PROC play (voice,code#) 
IF codes<>"2" THEN 
note (voice,code$) 
gate(voice,1) // attach and decay 
ENDIF 
pause(8) // sustain 
gate(voice,O) // release 
ENDPROC play 


PROC pause (sec ’32) 

TIME O 

WHILE TIME<1.875*sec ’32 DO NULL 
ENDPROC pause 


// save “@Music 3" 
DIM code# OF 2, answer? OF 5S 
USE sound 


LOOF 
PAGE 
PRINT "“Let’s play some notes together" 
FRINT "and create a simple melody...” 
PRINT AT 22,1: “LESSON S: We play a melody..." 


FOR voice:=1 TO = DO 
soundtype(voice,3) 
ENDFOR voice 


INFUT AT 4,1: "continue or end (c/e)? ": answers 
IF answer#="e" THEN STOF 
INFUT AT 6,1: "voice (1/2/2)7 ": voice 


play ‘melody 
ENDLOOF 


PROC play(voice,code$) 
IF code#<>"z" THEN 
note (voice,code#) 
gate(voice,1) // attack and decay 
ENDIF 
pause(tid) // sustain 
gate(voice,O) // release 
ENDFROC play 


FROC play’melody // Row, Row, Row Your Boat 


melody: 
DATA "c4" ,8,"2",2,"c4" ,8,"2",2,"c4",8,"d4" ,4 
DATA "e4",8,"2",8,"e4",8,"d4",4,"e4",8 
DATA "£4" ,4,"g4",16,"2",8,"c5",4 
DATA "c5",4,"c5",4,"°94",4,"94",4 
DATA "g4",4,"2e4",4,"2e4" ,4,"e4" ,4 
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0410 DATA "c4",4,"c4",4,"c4",4,"2",8,"g4",8 
0420 DATA "£4",4,"e4",8,"d4",4,"c4",8 

0430 

0440 RESTORE melody 

0450 WHILE NOT EOD DO 


0460 READ code#¢,tid 
0470 play (voice,code#) 
0480 ENDWHILE 

0490 

O500 ENDPROC play ‘melody 
0510 


0520 PROC pause (sec ‘32) 

0530 TIME O 

0540 WHILE TIME<1.875#s5ec °32 DO NULL 
OS550 ENDPROC pause 


0010 // save "@Music 4" 

0020 DIM code# OF 2 

0030 USE sound 

0040 

0050 LOOP 

0060 

0070 PAGE 

0080 PRINT AT 22,1: "LESSON 4: Sound level, type and ADSR..." 
0090 FRINT AT 1,1: "Sound level and sound type can be" 
0100 FRINT “selected for each voice." 

0110 PRINT 

0120 PRINT "Choose the parameters in SOUNDTYPE," 

01230 FRINT “and choose the ADSR values..." 

0140 FRINT 


0150 PRINT "Your choices will remain valid until" 
0160 PRINT "the parameters are redefined." 
0170 
0180 INFUT AT 11,1: "VOICE (1/2/2)7 ": voice 
0190 INPUT AT 13,1: "VOLUME (0-15)7 "s vol 
0200 INPUT AT 15,1: “SOUNDTYPE (1/2/2/4)7 ": type 
0210 soundtype (voice,type) 
0220 volume (vol ) 

250 PAGE 
0240 FRINT "Voice: "svoice;" — Sound type: ";type 


0250 PRINT “The sound level is"svol;"." 

0260 PRINT 

0270 PRIN) “--3-rrenn  n rr 2 
0280 FRINT "ADSR parameters: attack, decay," 
0290 PRINT “sustain and release are chosen... 
0300 PRINT 

0310 FRINT 


0320 FRINT " *" 

0330 PRINT " *% + Each parameter can" 
0340 PRINT "“ * HH HHH vary from O to 15." 
0350 FRINT " #* *" 

0360 PRINT “# *" 

0270 PRINT “" A D S R"“ 

0380 PRINT 

0390 PRINT "Az: attack time D: decay time" 
0400 PRINT "S: sustain level R: release time" 
$410 PRINT “--------------------------------------- " 
0420 INPUT AT 21,1: "A,D,S,R? ": a,d,syr 

0430 adsr (voice,a,d,s,r) 


0440 
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0450 
0460 
0470 
0480 
0490 
o500 
0510 
03520 
0530 
0540 
OS5S50 
05460 
0570 
0580 
0590 
0600 
04610 
0620 
0630 
0640 
0650 
0660 
0670 
0680 
0690 
0700 
0710 
0720 
0730 
O740 
0750 
0769 
0770 
0780 
0790 


0010 
0020 
0030 
0040 
0050 
0060 
0070 
0080 
0090 
0100 
0110 
0120 
0130 
0140 
0150 
0140 
0170 
0180 
0190 
0200 
0210 
0220 
0220 
0240 


play ‘melody 
ENDLOOP 


PROC play (voice,code?) 
IF code#<>"z" THEN 
note (voice ,code$) 
gate (voice,1) // attack and decay 
ENDIF 
pause(tid) // sustain 
gate(voice,9) // release 
ENDPROC play 


PROC play’melody // Row, Row, Row Your Boat 
melody: 

DATA "c4" ,8,°"2",2,"c4",8,"2",2,"c4",8,"d4",4 

DATA "e4" ,8,"2",8,"e4",8,"d4",4,"e4",8 

DATA "£4" .4,"g4",16,"2",8,"cS",4 

DATA "cS" ,4,"Cc5",4,"9g4",4,"g4",4 

DATA "g4",4,"2e4",4,"2e4" ,4,"2e4",4 

DATA "c4",4,"c4" ,4,"c4" ,4,"2",8,"94",8 

DATA "44" ,4,"e4",8,"d4",4,"c4",8 


RESTORE melody 
WHILE NOT EOD DO 
READ code#,tid 
Play (voice,code?) 
ENDWHILE 


ENDFROC play ’melody 


FROC pause (sec ’32) 

TIME O 

WHILE TIME<1.875*sec ‘32 DO NULL 
ENDPROC pause 


// save "@Music 5" 

DIM code# OF 3 

DIM tone#(50), ads ’pause#(S50), r ’pause#(50) 
USE sound 

volume (15) 

soundtype (1,2) 

adsr (1,6,6,8,6) 


no:=0 
WHILE NOT EQD DO 
no: +1 
READ code#,tim 
tone# (no) :=frequency (codes) 
ads’ pause# (no) :=tim#2 
r ‘pause# (no) :=timt2 
ENDWHILE 


tone# (no+1) :=0 
setscore(1,tone#() ,ads  pause#() ,r ‘pause#() ) 
Playscore(1,0,0) 


number :=0 
WHILE NOT waitscore(1,0,0) DO 
number :+1 


Appendix H - ~- 305 - SAMPLE PROGRAMS 
0250 PRINT number; 

0260 ENDWHILE 

0270 END 

0280 

0290 PROC pause (sec ’32) 

0300 TIME O 

0310 WHILE TIME<1.875%*sec ‘32 DO NULL 
0320 ENDFPROC pause 

0320 

0340 DATA "c4",8,"c4",8,"c4",8,"d4",4 
0350 DATA "e4",8,"e4",8,"d4",4,"e4",8 
0360 DATA "£4",4,"94",16,"c5",4 

0370 DATA "c5",4,"c5",4,"g4",4,"94",4 
0380 DATA "g4",4,"e4",4,"2e4",4,"e4",4 
0390 DATA "c4",4,"c4",4,"c4",4,"g4",8 
0400 DATA "44" ,4,"e4",8,"d4",4,"c4",8 
SPRITEEDITOR 


The program SPRITEEDITOR is on the COMAL demonstration 
diskette (and tape). This program can be used to create 
sprite images. A drawing which has been prepared and saved 
using this program can later be loaded into another program 
using the order: 


loadshape (<drawingno>,<filenames$>) 


The sprite editor program starts by displaying the 
following: 


SSOSSSSSSSSSSCSEESSESHS SESS 
eegeeueeenencenceengenggens ee MULTICOLOR: 9 
eeeeooeoeanoeooaenoenooeooeosoaeeo COLOR i: @ 
eseeeeeeeseoaeaeaeaeoeaeogeeeda EXPANDX: 6 
eesgeeeeeseaceesaeaeegaencaecs EXPANDY: 6 
eeeeceoceeueaeoeneesoaeeeeeeo BACKGROUND: e 
Seeeceeeeeceseaeeonoooucao COLOR 2: @ 
Seeeeeeeeeoneeoeneoaneseee COLOR 3: @ 
eeseeeeunenveeeenaeeeuneees 
eeeaeogoaeaeunaeoeueeeeoaeaoe se 
eeeeceeceocnueaegaaeeaaeseeeaesee 
eseeeoeceaeescenaenaneaaaeascn 
eeeceaeecoeaseeseoeeooeneeeeeeee 
eeeeeenaecaenenencooaaeeeooene 
eeecoeeaeeoeeseoeeeeseeece 
eesevecegneneeeuveneeeeen eee 
eeseeeeeceneaeneaaeneegeaee 
eeeaeseceaeoaeoaaeggeaeeaeaeesse PRESS: H 
eeeeseceoaooooaooesoaoesoase FOR HELP 
eeeeeeeeneeeceaeeseeeeeaeaese 
eeseeseeaengaeesaeecaeaeeeesesees 


Each of the dots corresponds to a dot on the screen. 
Movement of the drawing cursor from dot to dot is achieved 
using the cursor keys. The dots can be marked to indicate 
that they are to have a color different from the background 
color. 
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Choices are available from a menu shown on the right-hand 
side of the screen. If HELP is required, press H. A 
screen with user information will then appear. 


0010 
0020 
0030 
0040 
0050 


// save "@Addr List Demo" 

DIM replyt OF 1, name#(100) OF 40 

DIM street#(100) OF 40, city#(100) OF 40 
DIM phone#(100) OF 20, flag# OF 40 -; 

DIM searchkey# OF 40, string# OF i150 





0060 number:=0 // number of records 
0070 PAGE 
0o0sB0 PRINT "This program illustrates the use of" 
0090 PRINT “SEQUENTIAL FILES. It can be used to" 
0100 PRINT “create a list of names, addresses" 
0110 PRINT “and telephone numbers. " 
0120 PRINT “Each record will have the format: " 
0130 PRINT 
0140 PRINT " name" 
0150 PRINT "“ street" 
0160 FRINT " city” 
G170 PRINT “" phonenumber " 
0180 PRINT 
0190 PRINT 
O200 FRINT “Press any key to continue..." 
0210 
0220 wait ’for’keystroke 
ebe4 
0240 LOOF 
0250 show ‘menu 
0260 flag#:="" 
0270 wait for ‘keystroke 
0280 CASE reply? OF 
0290 WHEN "i" 
0200 load’file 
03210 WHEN "2" 
0320 create ‘record 
O33 WHEN "3" 
0340 list’file 
O350 WHEN "4" 
0260 search’file 
0370 WHEN "5S" 
0380 sort ‘file 
O290 WHEN "6" 
0400 change ‘record 
0410 WHEN "7" 
0420 delete ‘record 
0430 WHEN "8" 
0440 save file 
0450 OTHERWISE 
0450 FRINT "Illegal reply..." 
0470 wait for ‘keystroke 
0480 ENDCASE 
0490 ENDLOOP 
0500 
0510 PROC show’ menu 
0520 PAGE 
0530 PRINT “-----===== MAIN MENU =====-----— a 
0540 PRINT 
OSS PRINT 
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0560 PRINT " <1> LOAD the file" 

0570 PRINT " <2> CREATE a record" 

0580 PRINT " <5? LIST the file" 

0590 PRINT " <4> SEARCH the file" 

0600 PRINT “ <S> SORT alphabetically" 
0610 PRINT " <6> CHANGE a record" 

0620 PRINT " <7> DELETE a record" 

0630 PRINT " <B> SAVE revised file" 


0640 PRINT 

0650 PRINT 

0660 FRINT "Records: "snumber 
0670 IF number=O0 THEN flag#:="FPlease load or create a file..." 
0680 PRINT 

0690 PRINT flag? 

0700 ENDPROC show’ menu 

0710 

0720 PROC load’file 

0730 OPEN FILE 1,"Addresses",READ 
0740 INPUT FILE 1: number 

0750 FOR noz=1 TO number DO 


0760 INPUT FILE 1: name¥¢¥(no) 
0770 INPUT FILE 1: street#(no) 
0780 INPUT FILE 1: city#(no) 
0790 INPUT FILE 1: phone? (no) 


0800 ENDFOR no 

0810 CLOSE FILE 1 

0820 ENDFPROC load’file 

O830 

0840 PROC create’record 

0850 PAGE 

0860 PRINT "ses:: CREATE A NEW RECORD :::::" 

0870 PRINT 

O8B80O PRINT 

0890 IF number=100 THEN flag#:="No more room for data!” 


0900 IF flag#="" THEN 

0910 number:+1 

0920 INPUT "Name “: names (number ) 
0930 INFUT "Street ": street? (number ) 
0940 INFUT "City "s city? (number ) 
0950 INPUT "Fhone =": phone (number ) 


0960 ENDIF 

0970 ENDPROC create’record 

0980 

0990 PROC list’file 

1000 PAGE 

1010 PRINT “ss222 LISTING THE FILE :e::::" 
1020 PRINT 

1030 IF number=O0 THEN 


1040 flag#:="No files in memory!" 

1050 PRINT 

1060 ELSE 

1070 FOR no:=1 TO number DO print ’record(no) 


1080 ENDIF - 

1090 ENDPROC list’file 

1100 

1110 PROC search’ file 

1120 PAGE 

1130 PRINT "ss22: FILE SEARCH =:s:::" 
1140 PRINT 

1150 PRINT 

1160 flag#:="I am searching..." 
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1170 
1180 
1190 
1200 
1210 
1220 
1230 
1240 
1250 
1260 
1270 
1280 
1290 
1300 
1310 
1320 
1330 
1340 
1250 
1340 
1370 
1380 
1390 
1400 
1410 
1420 
1430 
1440 
1450 
1440 
1470 
1480 
1490 
1500 
1510 
1520 
1530 
1540 
1550 
1560 
1570 
1580 
1590 
1600 
1610 
14620 
1630 
1640 
1650 
1660 
1670 
1680 
14690 
1700 
1710 
1720 
1730 
1740 
1750 
1740 
1770 


INPUT “Search keys: ": searchkey$ 
FOR nos=1 TO number DO 
string$: =name$ (no) +street# (no) +city$ (no) +phone?s (no) 
IF searchkey$ IN string THEN print ‘record (no) 
ENDFOR no 
flag#:="" 
ENDPROC search‘file 


PROC print ’record (no) 
PRINT 
PRINT AT 0,10: *=--—-----—-—-—-—--= ("~no,")" 
PRINT AT 0,10: name$(no) 
PRINT AT 0,10: street#(no) 
PRINT AT 0,10: city#(no) 
PRINT AT 0,10: phone (no) 
PRINT 
wait ‘for ‘keystroke 
ENDPROC print ‘record 


FROC sort ’file 
PAGE 
PRINT “s:22: SORT BY NAME ALPHABETICALLY :::::" 
PRINT 
FRINT 


FROC swap (REF a#?,REF b#) CLOSED 
c#¥:=at; at :=bst3 bt: =cFt 
ENDPROC swap 


REPEAT 
no ’swap: =TRUE 
FOR no:=1 TO number-1 DO 
PRINT AT 10,1: "Sorting... ",no 
IF name (no+1)<namet (no) THEN 
swap (names (no) ,names (no+1) ) 
swap (street#(no) ,street¢(no+l)) 
swap (citys (no) ,city?# (no+1) ) 
swap (phones (no) ,phone$ (no+1)) 
no ‘swap: =FALSE 
ENDIF 
ENDFOR no 
UNTIL no’ swap 
ENDPROC sort ’file 


PROC change ‘record 
PAGE 
PRINT "“se:2:2:: CHANGE A RECORD ¢::3:::" 
PRINT 
PRINT 
INPUT “Which record number? "s no 
IF no<=number THEN 
print ‘record (no) 
INPUT AT 14,1: "Is this the right record ? (y/n)? "3s 
PRINT 
PRINT 
IF reply# IN "“yY" THEN 
INPUT "Name "“: name (no) 
INPUT "Street ": street$ (no) 
INPUT "City “s city$(no) 
INPUT "Phone phone$ (no) 
ENDIF 
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1780 
1790 
1800 
1810 
1820 
1830 
1840 
1850 
1860 
1870 
1880 
1890 
1900 
1910 
1920 
1930 
1940 
1950 
1960 
1970 
1980 
1990 
2000 
2010 
2020 
2030 
2040 
2050 
2060 
2070 
2980 
2090 
2100 
2110 
2120 
2130 
2146 
2150 
2160 
2170 
2180 
2190 
2200 
2210 
2220 
2230 
2240 
2290 
2260 
2270 
2280 
2290 
23500 
2310 


0010 
0050 
0060 
0097 
0100 


ELSE 
flag#:="There are only "+STR¢(number)+”" records" 
ENDIF 
ENDPROC change’‘record 


PROC delete’record 
PAGE 
PRINT "sss:: DELETE A RECORD ::2:::" 
PRINT 
PRINT 
INPUT "Which record number? ": record 
IF record>number THEN 
flag#:="Use a smaller record number'" 


ELSE 
print ‘record (record) 
PRINT 
INPUT “Is this the right record (y/n)? ": reply? 
PRINT 


IF reply# IN “yY" THEN 
FOR no:z=record TO number-1 DO 
names (no) : =nameF (no+1 ) 
street$ (no) :=street# (not+l) 
city# (no) :=city# (not!) 
phone? (no) : =phones (no+1) 


ENDFOR no 
number :-1 
ENDIF 
ENDIF 


ENDFROC delete’record 


PROC save’file 


PAGE 

PRINT "ss:22: SAVING FILE TO DISK e:::::" 
OPEN FILE 1,"“@Addresses" ,WRITE 

PRINT FILE 1: STR# (number ) 

FRINT 

PRINT 


FOR no:=1 TO number DO 
FRINT FILE 1: name#(no) 
FRINT FILE 1: street? (no) 
PRINT FILE 1: city#(no) 
PRINT FILE 1: phone# (no) 

ENDFOR no 

CLOSE FILE i 

ENDPROC save file 


PROC wait ’for ‘keystroke 
PRINT 
PRINT "< >..." 
REPEAT 
reply#:=KEYS 
UNTIL reply$S< >CHR$ (0) 
PRINT AT 0,2: replys 
ENDPROC wait’ for ’keystroke 


// save "@1520 Plotter Demo" 
setup ‘plotter 

DIM sc# OF i 

// 

// MAIN FROGRAM 
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0105 // 

0110 demo’size 

0120 demo’ color 

0130 demo’ case 

0140 demo’‘rotation 

0150 // 

0160 square (100) 

0165 blank’line(2) 

0170 dotlines(15) 

0175 blank’ line(8) 

0180 circle(240,240,200) 
0185 blank’line(14) 

0187 spinsquares (150) 
0190 // 

0192 setup ‘plotter 

0195 plotter ‘off & 
0197 // 

0200 END // MAIN FROGRAM 
0297 // 

0497 // 

OS00 FROC demo’size 
0510 FOR i:=0 TO 3 DO 


Oo515 select ‘size (i) 
0520 Pprint‘hello 
0525 blank’line(1) 


Q530 ENDFOR i 
0545 ENDFROC demo’size 


O547 // 

OS50 FROC demo‘color 
Oo555 select ’size(2) 
O560 FOR i:=0 TO 3 DO 
O3565 switch’ color (1) 
0570 print’hello 


0575 ENDFOR i 

0595 ENDFROC demo’color 
OS97 // 

0600 PROC demo’ case 
0605 blank ‘line(1) 


0610 select ‘case(QO) // upper case 
0615 Print ‘hello 
0620 select ’case(1) // lower case 


0625 print ‘hello 

0645 ENDFROC demo’case 
0647 // 

0650 PROC demo’rotation 
0655 blank ’line(2) 
0660 rot ‘char (1) 

0665 print “hello 

0670 rot ‘char (QO) 

0675 print ‘hello 

0695 ENDPROC demo’rotation 
0697 // 

0700 PROC dotlines(n) 
0705 zero ‘pen("“h") 
0710 FOR i:=0 TO n DO 





0715 plot ("m",0,—-1#20) 
O720 dot ‘line(i) 
0725 plot ("d",400,-1#20) 


0730 ENDFOR i 
0735 blank’ line(4) 
0740 dot ‘line (0) 
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0745 
0747 
0750 
07352 
0754 
07356 
0758 
0760 
0762 
0764 
0766 
0768 
0785 
0795 
0797 
0800 
0805 
0810 
0820 
0830 
0840 
0845 
0847 
O8S0 
oBs2 
0854 
0856 
0858 
0860 
0862 
0864 
0865 
0867 
0870 
0875 
O880 
osess 
0890 
0895 
0897 
0900 
0910 
Oo915 
0920 
0925 
0930 
0945 
0947 
0950 
0960 
0970 
0990 
0995 
0997 
1990 
1995 
1997 
2000 
2010 
2045 
2047 


ENDPROC dotlines 

// 

PROC circle(x0,y0,radius) 
plot ("m",xO,yO) 
zero’pen("i") 
Plot("r",radius,0O) 

FOR v:=0 TO 360 STEP 5 DO 
t:=P1I#v/180 
x?=radius*CO0S (t) 
y:=radius*SIN(t) 
Pplot("j",x,y) 

ENDFOR v 

blank’ line (4) 

ENDPROC circle 

// 

FROC square (side) 
blank ‘line(3) 
plot("j",0,side) 
plot ("j",side,side) 
plot("j",side,Q) 
plat("j",0,90) 

ENDPROC square 

// 

PROC spinsquares(s) 
plot ("m" ,240,240) 
zero’pen("i") 

FOR v:=0 TO 360 STEF 20 DO 
t:=PI#v/180 
draw ‘box (s,t) 

ENDFOR v 

blank ‘line (4) 

ENDFROC spinsquares 

// 

FROC draw’box (s,t) 
plat¢("j",s*COS(t) ,s¥SIN(t) ) 
plot("j",s*SQR (2) #COS (t+F1/4) ,s*SQR (2) SIN (tC+F1I/4) ) 
plot("j",s*eCOS(t+FI/2) ,s*¥SIN(t+FI/2) ) 
plot¢("j",0,0) 

ENDPROC draw’ box 

// 

FROC blank ‘line (bl) 
plotter ‘an 
FOR i:=1 TO bl DO 

PRINT FILE &: 

ENDFOR i 

plotter ‘off 

ENDPROC blank‘line 

// 

PROC print ‘hello 
plotter ’on 
PRINT FILE 6&6: "HELLO!" 
Plotter ‘off 

ENDPROC print ‘hello 

// 

// 

// PLOTTER PROCEDURES 

// 

PROC plotter ‘on 
OPEN FILE 6,"u6:" WRITE 

ENDPROC plotter ‘on 

// 
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2050 
2060 
2095 
2097 
2100 
2110 
2120 
2130 
2145 
2147 
2150 
2160 
2170 
2180 
2195 
2197 
2200 
2210 
2220 
2230 
2245 
2247 
2250 
220u 
2260 
2265 
2270 
2272 
22735 
2277 
2280 
2285 
2290 
2295 
2297 
2300 
2305 
2310 
2320 
23530 
2545 
2347 
2250 
2595 
2360 
2570 
2380 
2395 
2397 
2400 
2405 
2410 
2420 
2430 
2445 
2447 
2450 
2460 
2470 
2495 
2497 


PROC plotter ‘off 
CLOSE FILE 6 

ENDPROC plotter ‘off 

// 

PROC switch ‘color (pen) 
OPEN FILE 2,"“u6:/s2",WRITE 
PRINT FILE 2: pen 
CLOSE FILE 2 

ENDPROC switch ’color 

// 

PROC select ’size(size) 
OPEN FILE 3,"u6é:/s3" ,WRITE 
PRINT FILE 3: size 
CLOSE FILE 3 

ENDPROC select ’size 

// 

PROC select ‘ascii 
OPEN FILE 4,"u6:/s0" ,WRITE 
PRINT FILE 4: 
CLOSE FILE 4 

ENDPROC select ‘ascii 

// 

PROC plot (sct#,x,y) 
OPEN FILE 1,"u6:/s1" ,WRITE 
PRINT FILE 1: sc#sx;sy 
CLOSE FILE 1 

ENDPROC plot 

// 

PROC zero’pen(zp#) 
// zp% = hHh/i for abs/relative 
OFEN FILE 1,"u6:/si" ,WRITE 
PRINT FILE 1: zp? 
CLOSE FILE 1 

ENDPROC zero’pen 

// 

PROC rot ’char (rot)? 
// rot=0/1 for hor/rot 90 deg CW 
OPEN FILE 44, “ué6é:/s4",WRITE 
PRINT FILE 44: rot 
CLOSE FILE 44 

ENDFPROC rot ‘char 

// 

PROC dot ‘line(dash) 
//dash=0 to 15, O = unbroken 
OPEN FILE 5S, “u6é:/s5" ,WRITE 
PRINT FILE S: dash 
CLOSE FILE 5 

ENDPROC dot’line 

// 

PROC select ‘“case(nr) 
// nr=0/1 for upper/lower case 
OPEN FILE 6,“u6:/s6" ,WRITE 
PRINT FILE 6: nr 
CLOSE FILE 6 

ENDPROC select ‘case 

// 

PROC reset ‘plotter 
OPEN FILE 7,“ué:/s7" ,WRITE 
PRINT FILE 7s: 

ENDPROC reset ‘plotter 

// 


SAMPLE PROGRAMS 
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25300 PROC setup ‘plotter 


2505 
2510 
2015 
2020 
2020 
2950 
2045 


2047 


0010 
0020 
O00Z0 
0040 
0050 
0060 
0070 
0080 
0090 
0100 
0110 
0120 
0130 
0140 


0150 
0160 
0170 
0180 
0190 
0200 
0210 
0220 
0230 
0240 
0250 
0260 
0270 
0280 
0290 
0300 
0310 
0320 
0330 
0340 
0350 
0360 
0370 
0380 
0390 
0400 
0410 
0420 
0430 
0440 
0450 
0460 
0470 
0480 
0490 


select ’case(1) // lower case 
switch’color(1) // blue 

rot ’char(0O) // horizontal 
dot “line(O) // unbroken 
select ’size(1) // normal 
SELECT OUTPUT “ué:" 


ENDPROC setup ‘plotter 


// 

// save "@Train Demo" 

PAGE 

PRINT AT 2,2: “ELECTRIC TRAIN DEMO" 

PRINT AT 4,2: “Your train should start at the station" 
PRINT AT 5,2: “with the passage detector just behind" 
PRINT AT 6,2: “the last car. Start the train and then" 
PRINT AT 7,2: "press any key to turn control over" 
PRINT AT 8,2: “to your computer..." 

WHILE KEY#=CHR#¢ (0) DO NULL 


PAGE 
PRINT AT 2,2: “ELECTRIC TRAIN DEMO" 


// Fort B bit O can be connected to the collector of a 
Darlington 


// 
// 
// 
// 


Sf 


de 


Phototransistor. The emitter is connected 


to ground. 


Bit O will be low when the fototransistor is illuminated. 
Port B bit 1 should be connected to a transistor and relay 


so that bit 1 high starts the train. 
MAIN FROGRAM 


fine’variables 


set ‘port ’b 


st 
pr 


art ’train 
int’list 


REPEAT 


check ‘light 
delay(1.5) 
stop ’train 
delay (10) 
start ‘train 


UNTIL KEY#<>"" 


st 


op ‘train 


PAGE 
END "Au revoir!" 


// 


ALL PROCEDURES FOLLOW BELOW 


PROC print’list 


PRINT AT 12,4: "train running" 
PRINT AT 13,4: “train passes light" 
PRINT AT 14,4: "train waiting at station" 


PRINT AT 18,4: "Pressing any key will stop the train" 
PRINT AT 19,4: "next time it stops at the station..." 
ENDPROC print’list 


PROC start ’train 


FOKE port’b,PEEK(port’b) BITOR 2 


Appendix H - - 314- SAMPLE PROGRAMS 


03500 advance ‘pointer 
0510 ENDPROC start ‘train 
0520 


0530 PROC check ‘light 
0540 WHILE PEEK (port‘’b) BITAND 1<>1 DO NULL 


0550 advance ‘pointer 
0560 ENDPROC check’ light 
0570 


0580 PROC delay (sec) 

0590 TIME O 

0600 WHILE TIME<sec*60 DO NULL 
0610 ENDPROC delay 


0620 

0630 PROC stop’train 

0640 POKE port’b,PEEK(port’b) BITAND 253 

0650 advance ‘pointer @ 
0660 ENDPROC stop’train 

0470 


O&6B80 PROC define’variables 
04690 port ‘b:=#ddol 

0700 port ‘’b’ddr:=#dd03 

0710 position:=1 

0720 ENDPROC define’variables 
0730 

0740 PROC set ‘’port’b 

0750 POKE port ’b’ddr,2 

0760 POKE port’b,2- 

0770 ENDPROC set ’port’b 

0780 

0790 FROC advance’ pointer 
0800 PRINT AT 10+position,2: " " 
O810 IF position<4 THEN 


0820 position: =position+tl 
OB30 ELSE 
0840 position:=2 


0850 ENDIF 
0860 PRINT AT 10+position,2: ">" 
0870 ENDFROC advance’ pointer 
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@ 221,224,237 

A/D converters 251 

ABS 79, 131 

accessories 15 

accuracy 205 

action blocks 43 

actual parameters 73 

Addr List Demo 223,306 

address list 222 

ADSR 185,192 

ADSR envelope 186 

algorithm 77 

AND 1238 

AND THEN 139 

animate 178 

apostrophe 38 

AFPEND, file 113 

arc 1357 

arcl 159 

arcr 160 

arithmetic operators 281 

arrays 67 

arrays, one-dimensional 69 

arrays, text 70 

ASCII characters 275 

ASCII-format 113 

assembler language 25 

assignment operator 47 

asynchronous data 
transmission 242 

at symbol (@) 221,224,237 

ATN 132 

attack 189 

AUTO 24,93 


back 159 

background 154 

backup copy 41,42,46 
bank switching 261 
Basic 9,10,37 

Rasic fra COMAL 105 
Batteries Included 245 
bell 210 

Bendict Lefsted 10 
binary form 233 

BITOR 141 

BITXOR 141 

Boolean operators 282 
border 154 

branch blocks 43 
branching S9 

bubble sort 82,229 
Bus Card II 245 

byte 25 


calculations 281 
call procedure 39 
capital letters 21 
cartoons 1649 
cartridge, installation 17 
CASE structure 4l 
CASE—-OF—-WHEN-OTHERWISE-— 
ENDCASE 119 
CAT 97 
CBM 8050 & 8250 disk 
drives 245 
CHAIN 101,221 
CHANGE 95,227 
character codes 275 
character deletion 28 
character replacement 214 
character sets (font) 213 
character set, replacement 215 
character set, user-defined 215 
chip, 6910 25 
CHRE 133 
CHR#(O) SS 
Christensen, Berge 10 
circle 156 
circles 50 
clear 154 
clear/home 29 
clearscreen 30 
Cclearscreen 153 
CLOSE 116 
CLOSE FILE 116 
CLOSED 127 
Closed procedures 82,221 
collision, sprite i168 
color codes 31,279 
color combinations 279 
color TV 17 
color, foreground 172 
colors, screen 27 
COMAL cartridge 258 
COMAL files 219 
COMAL system 255 
comments (//) 141 
commercial-a (@) 
Commodore Data 10 
Commodore key 20,57,283 
computer language 32 
CON 101 
condition 59 
conditional executiion 39 
conditionals 117 
control key 285 
control ports 197 
control ports 251 
COPY 102 
corrections 299 
COS 132 


221,224,237 
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crash 8&8 
CREATE 112 
cs: 237 
curcol 210 
currow 210 
cursor 110 


Danish 148 

dansk 148 

DATA 110,223 

data direction register 247 

data element 223 

data statement 72 

data stream 86 

datacollision 1861 

Datassette 15,17,21,40,238 

DB-25 connector 246 

ddr 247 

decay 189 

declaration statement 56 

define (drawing) 174 

defkey 210 

DEL 95 

delay 204 

delete 103 

delete character 27 

delete key 20 

Demo Diskette 22 

Demo Program 21 

demonstation program 21 

digital thermometer 251 

DIM 142 

dimensioning string 
variables 56 

DIR 97 

direct execution 27 

direct files 232 

discard 30,106 

disk drive 15,22,237 

disk drives, CBM 245 

disk operating system 
errors 297 

diskette files 219 

display 99,220 

DIV 137 

DOS error messages 297 

draw 155 

drawing, save 168 

drawto 155 

ds: 237 

dynamic equals sign 47 


Easyscript 220 
EDIT 94 
empty statements 38 


INDEX 


END 145 

ENDTRAP 89 

english 148 

ENTER 99,220,221 

env3 195 

EOD 111 

EPROM expansion 258 
EPROM module 266 
equality sign 47 
equation, solving 77 
ERR-ERRFILE-ERRTEXTS 122 
error handling 86,122 
error messages 291 
error numbers 291 
error reporting 268 
ESC 136 

even parity 242 

EXIT WHEN 89 

EXP 133 

expression 48 
EXTERNAL 128 

external procedure 84,221 


FALSE 135 

file 86,219 

file handling 85 

file transfer between 
computers 250 

file type code 236 

file types 236 

fill 52,157 

filter 194 

filterfreq 194 

filtertype 194 

FIND 94 

fine-tuning of TV 20 

font package 213 


font procedures in depth 216 


FOR-ENDFOR 236 
FOR-TO-STEP-DO-ENDFOR 121 
foreground color 172 
formal parameters 73 
formatting 23 

forward 159 

free 210 

frequency 193 

fullscreen 153 
FUNC-RETURN-ENDFUNC 77,129 
function header 263 
function keys 284 
function, string 80 
functions 9,76,129,257 


game ports 251 
games 26 
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gate 192 

GET# 220 

getcharacter 217 
getcolor 155 
getscreen 208 
gettimes 208 

global names 74 

GOTO 124 

graphics 29 

graphics cursor 30 
graphics overview 150 
graphics package 31 
graphics screen 30,148 
graphics symbols 21 
graphics, use 149 
graphicscreen 152 
greeting message 20 


HANDLER 8&9 
hard copy, text screen 58 
hardcopy 209 
heading 158 
hidesprite 180 
hideturtle 158 
high-graphics screen 171 
high-level language 25 
high-resolution 

graphics 29,149,152,163 
high (voltage level) 242 
home 30,158 


I/QO port 245 

identify (sprite) 174 

IEEE cartridge 245 
IF-—THEN-ELIF—-ELSE-ENDIF 117 
IMPORT 84,128 

IN 140 

indentation 38 

index 68 

indexed variables 67 
initializing diskette 23 
inkey# 207 

INPUT 106 

INPUT AT 106 

INPUT FILE 88,114,220 

input port 245 

INPUT statement 49 

inputs 25 

ing 162 

insert key 20 

INST/DEL key 20 

instruction sequence 3i 

INT 131 

integers 233,264 : 
intensity envelope (sound) 195 


INDEX 


interrupt 196 


Jack connections 15 
Jensen, Jens Erik 10 
joysticks 199 


kb: 237 

keepfont 217 

kernel, COMAL 259 

KEY 35,65,107 

keyboard 20,237,283 
keywords 36 

keywords ‘in’upper ‘case 206 
Kjzr, Mogens 10 


label 111 

Lassen, Helge 10 
Laursen, Lars 10 

left 159 

LEN 135 

light pen 199 

light pen overview 204 
Lindsay, Len 11 

line numbers 34 

link 105,257 

linkfont 214,216 
linkshape 182 

LIST 98,220,221 

LOAD 100,220 

loadfont 216 
loadscreen 163 
loadshape 182 

local names 73 

LOG 133 

logical (bit) operators 281 
logical constants 59 
logical expressions 59 
Logo 9,37 

LOOP -—- ENDLOOP 79,89 
loop block 35,43,43 
loop statements 119 
LOOP-EXIT-EXIT WHEN-ENDLOOP 12: 
loops 63 

low (voltage level) 242 
lower case 28 

lp: 237 
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machine language 255 

MAIN 129 

memory management 260 

memory organization 258 

MERGE 99,220,221 

merging a procedure 222 

microcomputer 25 

microprocessor 25 

midpoint method 77 

MOD 137 

module signal routine 268 

modules 257 

modules, creating 262 

monitor 17 

MOUNT 112 

move 156 

movesprite 176 

moveto 155 

moving (sprite) 178 

multi-color graphics 
149,153,164 

multi-color screen 171 

Music 184,301 

Music =O1 

Music 302 

Music 303 

Music 304 


Ul Poh 


names ‘in’upper ‘case 207 
NEW 93 

Niklaus Wirth 10 

NOT 138 

note 191 

nowrap 160 

NTSC TV standard 184 
NULL 144 


odd parity 242 

offset 201,204 
one-dimensional arrays 69 
OPEN 112 

OPEN FILE 112 

operating environment 26 
operating system 255 

OR 139 

OR ELSE 139 

ORD 134 

order line 34 

oscS 195 

OTHERWISE 61 

output device 25 

output port 245 


package 30,147,257 
package concept i11 
package example 269 
packages, overview 147 
paddle game 198 
paddles 197 

page 279,49,109 

paint 157 

FAL TV standard 184 
parallel port 245 
parameter passing 263 
parameter specification 263 
parentheses 58 

parity bit 242 @ 
Pascal 9,10,37 

PASS 24,103 

PEEK 143 

pen 30 

pencolor 154 

pendown 159 

penon 204 

penup 159 

PI 122 

pixel 148,171 
playscore 193 

plot 155 

Plotter Demo 238 
plottext 161 

POKE 143 

power supply 19 

prg 236 

PRINT 28,107 

PRINT AT 108 

PRINT FILE 88,113 
PRINT USING 108 
printer 15 

printer attributes 211 
Printer-Plotter 238 
printscreen 163 
priority (operations) 281 @ 
priority (sprite) 180 
PROC-ENDPROC i125 
procedure. 9,25,52,58, 73,125,257 
procedure call 39 
procedure, closed 82 
procedure, external 84 
procedure header 263 
procedure name 39 
procedure oriented 26 
procedures, recursive 76 
procedures, saving 220 
program 32 

programming 26 
programming style 40 
programming habits 45 
programs, saving 220 
programs, samples 301 
protocol, RS-232C 242 
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pulse 195 
putcharacter 217 


Random File Demo 232 
random files 113,232 
random access files 219 
RANDOMIZE 136 

READ 110 

READ FILE 88,112,115 
READ statement 72 
readpen 204 

real numbers 234,264 
record 219,223 

recursion 76 

REF 127 

rel 236 

relational operators 282 
release 189 

RENAME 103 

RENUM 37,93 

REPEAT-UNTIL 65,119 
repeating instructions 35 
repetition 63 

REPORT 123 

resonance 195 

RESTORE 111 

RETURN key 28 

RETURN, from function call 129 
right 159 

ringmod 195 

RND 136 

roots, finding 78 
RS-232C interface 241,250 
RUN 34,101,121 


sample programs 301 
SAVE 100,220 

savefont 217 
savescreen 162 
saveshape 182 

Saving programs 40 
sawtooth wave (sound) 195 
SCAN 346,46,95 

screen 237 

screen characters 275 
screen colors 27 
screen editor 283 
search key 228 

SELECT INPUT 104 
SELECT OUTPUT 50,104 


INDEX 


semicolon 31 

seq 236 

sequential file 219,222 
sequential file, moving 235 
serial 211 

serial communication 241 
setexec 96 

setfrequency 193 
setheading 158 

setpage 212 

setprinter 211 
setrecorddelay 212 
setscreen 209 

settime 207 

setxy 156 

SGN 79,1231 

shift 20 

shift lock 20 

showkeys 211 

showsprite 180 
showturtle 158 

SID chip 184 

signal routines 267 
Signals 257 

Simulations 27 

SIN 132 

SIZE 97 

sorting, bubble 82 

sound 184 

sound default values 190 
sound orders in depth 191 
sound package 184 

sound synthesizer 184 
soundtype 185,192 

spo: 227 

SPCt 

split screen 29 
splitscreen 1523 

sprite drawing, save 168 
sprite orders 150 
sprite overview 173 
sprite package 165 
sprite, multi-colored 175 
spriteback 175 
spritecollision 180 
spritecolor 174 
spriteeditor 305 
spriteing 1861 

spritepos 175 

sprites 165 

sprites, enlarged 167 
sprites, multi-colored 171 
spritesize 175 

spritex 178 

spritey 178 

SQR 132 

square, drawing 33 
square wave (sound) 196 
stampsprite 181 

Star Trek 26 
startsprites 178 
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state 33 

statement 54 

STATUS 102 

STATUS$ 102 

STOP 144 

stop bit 242 

stopplay 193 
stopsprite 178 
storage diskette 23,41 
storage medium 219 
STR? 134 

string 55,264 

string constant 56 
string functions 80,289 
string segments 288 
string variable 56 
strings 234 

structure, program 40 
structured programming 9 
style, programming 40 
sustain 189 

SxX-64 16 

symbols 12 

sync 194 

SYS 144 

SYS to COMAL 105 
system package 206 


TAB 109 

TAN 132 

tape files 219 
temperature 252 

text S5 

text arrays 70 

text editor 220 

text handling 287 

text screen 30,148 
textbackground 154 
textborder 154 

textcolor 154 

textcolors 206 
textscreen 153 
textstyle 161 
thermometer, digital 251 
three line interface 243 
TIME 135 

timeon 205 

Total Turtle Trip Theorem 37 
TRACE 142 

train demo 247 

train demo 313 

TRAP 89 

TRAP ESC i136 
TRAP—-HANDLER-ENDTRAP 122 
triangle wave (sound) 195 
TRUE 125 

turtle 30,33 

turtle graphics 9,29 


INDEX 


turtle package orders 151 
turtle, use 149 
turtlesize 158 
TV signal, fine tuning 20 


us<device> 237 

UHF signal 19 
UniComal ApS 10 

UNIT 116,237 

UNITS 116 

upper case 28 

USE 105 

user comments 299 
users’ groups 11,255 
USR 236 


VAL 134 
variable names 39 


‘variables 47 


variables, indexed 467,68 

VERIFY 102 

version 2.0 10 

viewport 150,152 

voices (music) 184 

voltage levels, serial 
interface 242 

volume 185,191 


waitscore 193 

waveform envelope i185 
waveform parameters 188 
WHILE-DO-ENDWHILE 120 
white noise (sound) 196 
window 150,152 

wrap 160 

WRITE FILE 88,113,114,233 
write protection 22 


xcor 157 

ycor 157 

ZONE 29,109 

Arhus University 10 
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